{"id":13623389,"url":"https://github.com/alexanderjarvis/maybe","last_synced_at":"2025-04-15T14:32:51.907Z","repository":{"id":57292818,"uuid":"82199838","full_name":"alexanderjarvis/maybe","owner":"alexanderjarvis","description":"Maybe is a type that wraps optional values","archived":false,"fork":false,"pushed_at":"2018-10-19T02:32:37.000Z","size":88,"stargazers_count":302,"open_issues_count":4,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-04-12T05:09:58.362Z","etag":null,"topics":["javascript","js","maybe"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/alexanderjarvis.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2017-02-16T16:14:49.000Z","updated_at":"2024-09-21T12:43:53.000Z","dependencies_parsed_at":"2022-08-27T16:51:03.999Z","dependency_job_id":null,"html_url":"https://github.com/alexanderjarvis/maybe","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexanderjarvis%2Fmaybe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexanderjarvis%2Fmaybe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexanderjarvis%2Fmaybe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexanderjarvis%2Fmaybe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexanderjarvis","download_url":"https://codeload.github.com/alexanderjarvis/maybe/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249089053,"owners_count":21210907,"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":["javascript","js","maybe"],"created_at":"2024-08-01T21:01:31.196Z","updated_at":"2025-04-15T14:32:51.650Z","avatar_url":"https://github.com/alexanderjarvis.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Maybe [![Build Status](https://travis-ci.org/alexanderjarvis/maybe.svg?branch=master)](https://travis-ci.org/alexanderjarvis/maybe) [![npm version](https://badge.fury.io/js/maybes.svg)](https://badge.fury.io/js/maybes)\n\nMaybe is a type that wraps optional values. It can either be a `Just` (has some value) or a `Nothing`\n(has no value).\n\nIt's defined like this: `type Maybe\u003cA\u003e = Just\u003cA\u003e | Nothing`\n\nIn JavaScript, it is a better way of handling `null` and `undefined`. Instead of writing an if\nstatement, ternary expression, or `\u0026\u0026` shorthand to check if a value is present you can just `map`\nover it instead and assign the result of this expression or return it. You can also chain operations\ntogether, often leading to much cleaner code.\n\nIt's inspired by Haskell's [Maybe](https://wiki.haskell.org/Maybe), Swift's [Optional](https://developer.apple.com/reference/swift/optional) and\nScala's [Option](http://www.scala-lang.org/api/current/scala/Option.html).\n\n## Installation\n\nUsing yarn\n\n```\n$ yarn add maybes\n```\n\nor npm\n\n```\n$ npm install maybes\n```\n\n## Usage\n\nImport the library:\n\n```js\nimport { maybe } from 'maybes'\n```\n\nor if you want everything:\n\n```js\nimport { maybe, just, nothing } from 'maybes'\n```\n\nUse the `maybe` function to create a `Maybe` from a value.\n\n```js\nconst value = maybe(1) // Just(1)\n\nvalue.isJust() // true\nvalue.isNothing() // false\n```\n\nUse `map` to transform the value inside the `Maybe`.\n\n```js\nvalue.map(v =\u003e v + 1) // Just(2)\n```\n\nForce unwrap the value with `just()` if it is present. Warning: this will throw an Error if it\nis a `Nothing` (has no value).\n\n```js\nvalue.just() // 1 (or throws Error)\n```\n\nUse the `maybe` function to wrap a possibly empty value.\n\n```js\nconst empty = maybe(null)\n\nempty.isJust() // false\nempty.isNothing() // true\n\nempty.map(v =\u003e v + 1) // noop (No Operation)\nempty.just() // throws error\n```\n\nUse `orJust()` to provide a default value.\n\n```js\nempty.map(v =\u003e v.toUpperCase()).orJust('hello') // 'hello'\n```\n\nUse `orElse()` to provide a default already wrapped in a Maybe. This can be useful if you want to combine\ntwo or more Maybe's together.\n\n```js\nconst hello = maybe('hello')\nempty.map(v =\u003e v.toUpperCase()).orElse(hello) // Maybe('hello')\n```\n\nChain operations together using `map`:\n\n```js\nconst m = maybe('Maybe  ')\nconst result = m\n  .map(v =\u003e v.trim())\n  .map(v =\u003e v.toUpperCase()) // Just('MAYBE')\n```\n\nUse `flatMap` if you need to return a `Maybe` in your closure instead of the value. For example,\nwhen you want to explicitly return `Nothing` in a particular case.\n\n```js\nconst a = maybe('hi')\nconst result = a.flatMap(v =\u003e {\n  if (v === 'hi') {\n    return just('world')\n  } else {\n    return nothing\n  }\n})\n```\n\n`just` is a function like `maybe` that takes a value. `nothing` is a reference to `Nothing`.\n\nUsing `filter` is usually the best way to return a `Nothing` given a predicate. It returns\n`Just` only if there is a value and applying the predicate function to the `Maybe`'s value returns\n`true`.\n\n```js\nconst name = maybe('  ')\nconst upper = name\n  .map(v =\u003e v.trim())\n  .filter(v =\u003e v.length != 0)\n  .map(v =\u003e v.toUpperCase())\n```\n\nUse `forEach` when you would otherwise use `map` but can't or don't want to return a value. This\nis usually when you are causing a side effect. `forEach` returns `void` and so enforces it's the\nlast in a chain. It runs only if there is a non empty value.\n\n```js\nmaybe('effect').forEach(s =\u003e console.log(s))\n```\n\n## Types\n\nThis library uses [Flowtype](https://flowtype.org) so you can also import the `Maybe` type and use\nits definition:\n\n```js\nimport { maybe } from 'maybes'\nimport type { Maybe } from 'maybes'\n\nfunction getSomething(): Maybe\u003cstring\u003e {\n  return maybe('something')\n}\n```\n\nDon't worry if you don't use Flowtype though as it gets stripped by Babel.\n\n## Comparison with vanilla JavaScript\n\n#### Ternary function that optionally calls another function called `transform`.\n\nWithout Maybe\n\n```js\n(value) ? transform(value) : null\n```\n\n(Safe version in case value is falsy, e.g. `0`)\n```js\n(value != null) ? transform(value) : null\n```\n\nWith Maybe (handles falsy values like `0` and `''` automatically).\n\n```js\nmaybe(value).map(transform)\n```\n\n#### \u0026\u0026 and || shorthand\n\nWithout Maybe\n```js\nconst object: ?Object = {\n  value?: 'hello'\n}\n\nobject \u0026\u0026 object.value \u0026\u0026 object.value.toUpperCase() || ''\n```\n\nWith Maybe\n```js\nmaybe(object).flatMap(o =\u003e maybe(o.value).map(v =\u003e v.toUpperCase())).orJust('')\n```\n\nWith types already converted to `Maybe`'s.\n```js\nconst object = maybe({\n  value: maybe('hello')\n})\n\nobject.flatMap(o =\u003e o.value.map(v =\u003e v.toUpperCase())).orJust('')\n```\n\n## License\n\nMaybe is available under the MIT license. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexanderjarvis%2Fmaybe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexanderjarvis%2Fmaybe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexanderjarvis%2Fmaybe/lists"}