{"id":46301510,"url":"https://github.com/onegen-dev/optional.ts","last_synced_at":"2026-03-04T11:10:12.095Z","repository":{"id":284849269,"uuid":"852982845","full_name":"onegen-dev/optional.ts","owner":"onegen-dev","description":"TypeScript ‘Optional’ utility wrapper based on C++ ‘std::optional’","archived":false,"fork":false,"pushed_at":"2024-10-29T14:18:00.000Z","size":141,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-14T06:21:54.616Z","etag":null,"topics":["cpp","typescript","utility","utility-classes","wrapper"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/onegen-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-09-05T19:11:25.000Z","updated_at":"2024-09-11T22:13:47.000Z","dependencies_parsed_at":"2025-03-28T02:00:05.439Z","dependency_job_id":null,"html_url":"https://github.com/onegen-dev/optional.ts","commit_stats":null,"previous_names":["onegentig/optional.ts","onegen-dev/optional.ts"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/onegen-dev/optional.ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onegen-dev%2Foptional.ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onegen-dev%2Foptional.ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onegen-dev%2Foptional.ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onegen-dev%2Foptional.ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onegen-dev","download_url":"https://codeload.github.com/onegen-dev/optional.ts/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onegen-dev%2Foptional.ts/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30078586,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T08:01:56.766Z","status":"ssl_error","status_checked_at":"2026-03-04T08:00:42.919Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["cpp","typescript","utility","utility-classes","wrapper"],"created_at":"2026-03-04T11:10:11.357Z","updated_at":"2026-03-04T11:10:12.083Z","avatar_url":"https://github.com/onegen-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @onegen/optional\n\n[\n     ![NPM Downloads](https://img.shields.io/npm/d18m/%40onegen%2Foptional?style=for-the-badge\u0026logo=npm\u0026label=Downloads)\n](https://www.npmjs.com/package/@onegen/optional)\n\n`Optional` utility class in TypeScript, based on C++\n[`std::optional`](https://en.cppreference.com/w/cpp/utility/optional).\n\nMade as minimally as I could, without any dependencies. \\\nI just like how `std::optional` works and wanted it in JS/TS. \\\nGuess it’s mostly done unless I find some mistake or something. 🤷🏼‍♂️\n\n```ts\nimport { Optional } from \"@onegen/optional\";\n\nfunction saferDiv (x: number, y: number): Optional\u003cnumber\u003e {\n     if (y === 0) return Optional.nullopt;\n     return Optional.some(x / y);\n}\n\nvar result = saferDiv(2, 0);\nif (!result.hasValue())\n     console.log('Dividing by zero again, you dummy?');\nelse\n     console.log('It’s ', result.value(), '!');\n```\n\n`Optional` is a wrapper helper class around a value that may or may not\nbe defined. Instead of returning some arbitrary value (like -1),\n`null` or throwing an error, `Optional` can be returned, prompting you\n– the dev – to first check if there is any value before actually using it\nin a fun and type safe manner! \\\nLook, it’s not for everyone, but I like it.\n\n## Working with `Optional`s\n\n### Declaring\n\n```typescript\nimport { Optional, some } from '@onegen/optional';\n\nvar opt1 = new Optional\u003cnumber\u003e(2024);\nvar opt2 = Optional.some(2024);\nvar opt3 = some(2024)\n```\n\nAll of these lines are equivalent. They create an `Optional` holding a number\nvalue 2024. First line specifies the type explicitly, second implies it from\nits value, third line is just a shorthand for the second.\n\nAs you – a smart TypeScript developer – might’ve guessed, you can’t change the\n`Optional` type. Once you make an instance of `Optional\u003cT\u003e`, the variable will\nonly ever have `Optional\u003cT\u003e`.\n\n```typescript\nvar opt = Optional.some(2024);\nopt = Optional.some('2024'); // TS won’t let you do this!\n```\n\nWhile you can’t change the type, you can, of course, change the value:\n\n```typescript\nopt.assign(2026); // with a method, or\nopt = Optional.some(2025); // by re-assigning\n```\n\n…and even remove it:\n\n```typescript\nopt.reset(); // with a method, or\nopt = Optional.none(); // by re-assigning\nopt = Optional.nullopt; // equivalent to Optional.none()\n```\n\nDo mind that this doesn’t clear the variable type. The variable is still\n`Optional\u003cnumber\u003e`, even if `nullopt`. It will ever contain only a number\nor nothing.\n\n### Typeless declaration\n\nBe mindful when creating empty `Optional`s:\n\n```typescript\nvar opt = Optional.none()\n```\n\nThe type of `opt` is `Optional\u003cunknown\u003e` and that is not something you really\nwant now. I wish I could somehow forbid this. Seriously, don’t do this.\nWhen making an empty `Optional`, specify its type explicitly, for your\nown sake:\n\n```typescript\nvar opt: Optional\u003cnumber\u003e = Optional.none();\nvar opt = new Optional\u003cnumber\u003e();\n```\n\n### Base usage\n\nThe main advantage of `Optional` is that you don’t need an arbitrary\n\"did not work\" value (-1) or use `null`s that you may forgot to check for.\n`Optional` makes it natural (at least for me) to check if it has a value\nbefore actually using it:\n\n```typescript\nconst result: Optional\u003cnumber\u003e = saferDivide(10, 0);\nif (!result.hasValue())\n     return \"Whoops, something went wrong!\"\n\nconst value = result.value();\n```\n\nCalling `result.value()` while there is no value will lead to an error.\n\nThis little utility is not attempting to be Rust `Result`. If you want a more\nrobust error-handling utility, you might want to take a look at\n[neverthrow](https://github.com/supermacro/neverthrow).\nFully recommend (not sponsored).\n\n### Functions\n\n#### Observers\n\n| Function | Return Type | Description |\n| :-----------------------------------: | :-------: | :------------------------------------------------------------------------------: |\n| `Optional.hasValue()` | `boolean` | Checks whether the object contains a value |\n| `Optional.value()` | `T` | Returns the included value (throws error if there is none) |\n| `Optional.valueOr(defaultValue: T)` | `T` | Returns either the included value OR provided default value |\n\n#### Modifiers\n\n| Function | Return Type | Description |\n| :-----------------------------------: | :-------: | :------------------------------------------------------------------------------: |\n| `Optional.reset()` | `this` | Removes the contained value |\n| `Optional.assign()` | `this` | Assigns a new contained value |\n| `Optional.swap(other: Optional\u003cT\u003e)` | `this` | Swaps values of same-type Optionals |\n\nC++ also has [`emplace()`](https://en.cppreference.com/w/cpp/utility/optional/emplace),\nbut TS types cannot be used to make new instances, as far as I know.\n\n`assign()` is also deviance from `std::optional`, but I chose to add it, as TS/JS\ndoes not allow operator overloading.\n\nAlso, all modifier methods return themselves (`this`) to allow chaining.\n\n```ts\nvar opt = Optional.some(2024);\nopt.reset().assign(2025).reset();\n```\n\n#### Monadic Operations\n\n| Function | Return Type | Description |\n| :-----------------------------------: | :-------: | :------------------------------------------------------------------------------: |\n| `Optional.andThen\u003cU\u003e (fn: (value: T) =\u003e Optional\u003cU\u003e)` | `Optional\u003cU\u003e` | – |\n| `Optional.transform\u003cU\u003e (fn: (value: T) =\u003e U)` | `Optional\u003cU\u003e` | – |\n| `Optional.orElse (fn: () =\u003e Optional\u003cT\u003e)` | `Optional\u003cU\u003e` | – |\n\nThese are harder to explain in short Markdown table, there are simple usage examples\nin [`optional-mon.test.ts`](test/optional-mon.test.ts). Who am I even writing this for\nnobody will use this except me lmao.\n\n## Licence\n\n\u003cimg\n     alt=\"MIT-emblem\"\n     src=\".github/mit.png\"\n     width=\"15%\" /\u003e\n\n**@onegen/optional** is available as an open-source utility library licenced\nunder the [MIT Licence](https://en.wikipedia.org/wiki/MIT_License).\n\n- \u003cspan title=\"Too long; didn't read; not a lawyer\"\u003eTL;DR;NAL\u003c/span\u003e:\n   Do absolutely whatever you want with the code, just include\n   the LICENCE file if you re-distribute it.\n- See [`LICENCE`](LICENCE) file or\n   [tl;drLegal](https://www.tldrlegal.com/license/mit-license)\n   for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonegen-dev%2Foptional.ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonegen-dev%2Foptional.ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonegen-dev%2Foptional.ts/lists"}