版博士V2.0程序
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 

1203 lines
29 KiB

  1. import { getApplicativeMonoid } from './Applicative';
  2. import { apFirst as apFirst_, apS as apS_, apSecond as apSecond_, getApplySemigroup as getApplySemigroup_ } from './Apply';
  3. import { bind as bind_, chainFirst as chainFirst_ } from './Chain';
  4. import { chainEitherK as chainEitherK_, fromEitherK as fromEitherK_, chainFirstEitherK as chainFirstEitherK_ } from './FromEither';
  5. import { constNull, constUndefined, flow, identity, pipe } from './function';
  6. import { let as let__, bindTo as bindTo_, flap as flap_ } from './Functor';
  7. import * as _ from './internal';
  8. import { not } from './Predicate';
  9. import { first, last } from './Semigroup';
  10. import { separated } from './Separated';
  11. import { wiltDefault, witherDefault } from './Witherable';
  12. import { guard as guard_ } from './Zero';
  13. // -------------------------------------------------------------------------------------
  14. // constructors
  15. // -------------------------------------------------------------------------------------
  16. /**
  17. * `None` doesn't have a constructor, instead you can use it directly as a value. Represents a missing value.
  18. *
  19. * @category constructors
  20. * @since 2.0.0
  21. */
  22. export var none = _.none;
  23. /**
  24. * Constructs a `Some`. Represents an optional value that exists.
  25. *
  26. * @category constructors
  27. * @since 2.0.0
  28. */
  29. export var some = _.some;
  30. export function fromPredicate(predicate) {
  31. return function (a) { return (predicate(a) ? some(a) : none); };
  32. }
  33. /**
  34. * Returns the `Left` value of an `Either` if possible.
  35. *
  36. * @example
  37. * import { getLeft, none, some } from 'fp-ts/Option'
  38. * import { right, left } from 'fp-ts/Either'
  39. *
  40. * assert.deepStrictEqual(getLeft(right(1)), none)
  41. * assert.deepStrictEqual(getLeft(left('a')), some('a'))
  42. *
  43. * @category constructors
  44. * @since 2.0.0
  45. */
  46. export var getLeft = function (ma) { return (ma._tag === 'Right' ? none : some(ma.left)); };
  47. /**
  48. * Returns the `Right` value of an `Either` if possible.
  49. *
  50. * @example
  51. * import { getRight, none, some } from 'fp-ts/Option'
  52. * import { right, left } from 'fp-ts/Either'
  53. *
  54. * assert.deepStrictEqual(getRight(right(1)), some(1))
  55. * assert.deepStrictEqual(getRight(left('a')), none)
  56. *
  57. * @category constructors
  58. * @since 2.0.0
  59. */
  60. export var getRight = function (ma) { return (ma._tag === 'Left' ? none : some(ma.right)); };
  61. var _map = function (fa, f) { return pipe(fa, map(f)); };
  62. var _ap = function (fab, fa) { return pipe(fab, ap(fa)); };
  63. var _chain = function (ma, f) { return pipe(ma, chain(f)); };
  64. var _reduce = function (fa, b, f) { return pipe(fa, reduce(b, f)); };
  65. var _foldMap = function (M) {
  66. var foldMapM = foldMap(M);
  67. return function (fa, f) { return pipe(fa, foldMapM(f)); };
  68. };
  69. var _reduceRight = function (fa, b, f) { return pipe(fa, reduceRight(b, f)); };
  70. var _traverse = function (F) {
  71. var traverseF = traverse(F);
  72. return function (ta, f) { return pipe(ta, traverseF(f)); };
  73. };
  74. /* istanbul ignore next */
  75. var _alt = function (fa, that) { return pipe(fa, alt(that)); };
  76. var _filter = function (fa, predicate) { return pipe(fa, filter(predicate)); };
  77. /* istanbul ignore next */
  78. var _filterMap = function (fa, f) { return pipe(fa, filterMap(f)); };
  79. /* istanbul ignore next */
  80. var _extend = function (wa, f) { return pipe(wa, extend(f)); };
  81. /* istanbul ignore next */
  82. var _partition = function (fa, predicate) {
  83. return pipe(fa, partition(predicate));
  84. };
  85. /* istanbul ignore next */
  86. var _partitionMap = function (fa, f) { return pipe(fa, partitionMap(f)); };
  87. /**
  88. * @category type lambdas
  89. * @since 2.0.0
  90. */
  91. export var URI = 'Option';
  92. /**
  93. * @category instances
  94. * @since 2.0.0
  95. */
  96. export var getShow = function (S) { return ({
  97. show: function (ma) { return (isNone(ma) ? 'none' : "some(".concat(S.show(ma.value), ")")); }
  98. }); };
  99. /**
  100. * @example
  101. * import { none, some, getEq } from 'fp-ts/Option'
  102. * import * as N from 'fp-ts/number'
  103. *
  104. * const E = getEq(N.Eq)
  105. * assert.strictEqual(E.equals(none, none), true)
  106. * assert.strictEqual(E.equals(none, some(1)), false)
  107. * assert.strictEqual(E.equals(some(1), none), false)
  108. * assert.strictEqual(E.equals(some(1), some(2)), false)
  109. * assert.strictEqual(E.equals(some(1), some(1)), true)
  110. *
  111. * @category instances
  112. * @since 2.0.0
  113. */
  114. export var getEq = function (E) { return ({
  115. equals: function (x, y) { return x === y || (isNone(x) ? isNone(y) : isNone(y) ? false : E.equals(x.value, y.value)); }
  116. }); };
  117. /**
  118. * The `Ord` instance allows `Option` values to be compared with
  119. * `compare`, whenever there is an `Ord` instance for
  120. * the type the `Option` contains.
  121. *
  122. * `None` is considered to be less than any `Some` value.
  123. *
  124. *
  125. * @example
  126. * import { none, some, getOrd } from 'fp-ts/Option'
  127. * import * as N from 'fp-ts/number'
  128. *
  129. * const O = getOrd(N.Ord)
  130. * assert.strictEqual(O.compare(none, none), 0)
  131. * assert.strictEqual(O.compare(none, some(1)), -1)
  132. * assert.strictEqual(O.compare(some(1), none), 1)
  133. * assert.strictEqual(O.compare(some(1), some(2)), -1)
  134. * assert.strictEqual(O.compare(some(1), some(1)), 0)
  135. *
  136. * @category instances
  137. * @since 2.0.0
  138. */
  139. export var getOrd = function (O) { return ({
  140. equals: getEq(O).equals,
  141. compare: function (x, y) { return (x === y ? 0 : isSome(x) ? (isSome(y) ? O.compare(x.value, y.value) : 1) : -1); }
  142. }); };
  143. /**
  144. * Monoid returning the left-most non-`None` value. If both operands are `Some`s then the inner values are
  145. * concatenated using the provided `Semigroup`
  146. *
  147. * | x | y | concat(x, y) |
  148. * | ------- | ------- | ------------------ |
  149. * | none | none | none |
  150. * | some(a) | none | some(a) |
  151. * | none | some(b) | some(b) |
  152. * | some(a) | some(b) | some(concat(a, b)) |
  153. *
  154. * @example
  155. * import { getMonoid, some, none } from 'fp-ts/Option'
  156. * import { SemigroupSum } from 'fp-ts/number'
  157. *
  158. * const M = getMonoid(SemigroupSum)
  159. * assert.deepStrictEqual(M.concat(none, none), none)
  160. * assert.deepStrictEqual(M.concat(some(1), none), some(1))
  161. * assert.deepStrictEqual(M.concat(none, some(1)), some(1))
  162. * assert.deepStrictEqual(M.concat(some(1), some(2)), some(3))
  163. *
  164. * @category instances
  165. * @since 2.0.0
  166. */
  167. export var getMonoid = function (S) { return ({
  168. concat: function (x, y) { return (isNone(x) ? y : isNone(y) ? x : some(S.concat(x.value, y.value))); },
  169. empty: none
  170. }); };
  171. /**
  172. * @category mapping
  173. * @since 2.0.0
  174. */
  175. export var map = function (f) { return function (fa) {
  176. return isNone(fa) ? none : some(f(fa.value));
  177. }; };
  178. /**
  179. * @category instances
  180. * @since 2.7.0
  181. */
  182. export var Functor = {
  183. URI: URI,
  184. map: _map
  185. };
  186. /**
  187. * @category constructors
  188. * @since 2.7.0
  189. */
  190. export var of = some;
  191. /**
  192. * @category instances
  193. * @since 2.10.0
  194. */
  195. export var Pointed = {
  196. URI: URI,
  197. of: of
  198. };
  199. /**
  200. * @since 2.0.0
  201. */
  202. export var ap = function (fa) { return function (fab) {
  203. return isNone(fab) ? none : isNone(fa) ? none : some(fab.value(fa.value));
  204. }; };
  205. /**
  206. * @category instances
  207. * @since 2.10.0
  208. */
  209. export var Apply = {
  210. URI: URI,
  211. map: _map,
  212. ap: _ap
  213. };
  214. /**
  215. * @category instances
  216. * @since 2.7.0
  217. */
  218. export var Applicative = {
  219. URI: URI,
  220. map: _map,
  221. ap: _ap,
  222. of: of
  223. };
  224. /**
  225. * Composes computations in sequence, using the return value of one computation to determine the next computation.
  226. *
  227. * @category sequencing
  228. * @since 2.0.0
  229. */
  230. export var chain = function (f) { return function (ma) {
  231. return isNone(ma) ? none : f(ma.value);
  232. }; };
  233. /**
  234. * @category instances
  235. * @since 2.10.0
  236. */
  237. export var Chain = {
  238. URI: URI,
  239. map: _map,
  240. ap: _ap,
  241. chain: _chain
  242. };
  243. /**
  244. * @category instances
  245. * @since 2.7.0
  246. */
  247. export var Monad = {
  248. URI: URI,
  249. map: _map,
  250. ap: _ap,
  251. of: of,
  252. chain: _chain
  253. };
  254. /**
  255. * @category folding
  256. * @since 2.0.0
  257. */
  258. export var reduce = function (b, f) { return function (fa) {
  259. return isNone(fa) ? b : f(b, fa.value);
  260. }; };
  261. /**
  262. * @category folding
  263. * @since 2.0.0
  264. */
  265. export var foldMap = function (M) { return function (f) { return function (fa) {
  266. return isNone(fa) ? M.empty : f(fa.value);
  267. }; }; };
  268. /**
  269. * @category folding
  270. * @since 2.0.0
  271. */
  272. export var reduceRight = function (b, f) { return function (fa) {
  273. return isNone(fa) ? b : f(fa.value, b);
  274. }; };
  275. /**
  276. * @category instances
  277. * @since 2.7.0
  278. */
  279. export var Foldable = {
  280. URI: URI,
  281. reduce: _reduce,
  282. foldMap: _foldMap,
  283. reduceRight: _reduceRight
  284. };
  285. /**
  286. * Less strict version of [`alt`](#alt).
  287. *
  288. * The `W` suffix (short for **W**idening) means that the return types will be merged.
  289. *
  290. * @category error handling
  291. * @since 2.9.0
  292. */
  293. export var altW = function (that) { return function (fa) {
  294. return isNone(fa) ? that() : fa;
  295. }; };
  296. /**
  297. * Identifies an associative operation on a type constructor. It is similar to `Semigroup`, except that it applies to
  298. * types of kind `* -> *`.
  299. *
  300. * In case of `Option` returns the left-most non-`None` value.
  301. *
  302. * | x | y | pipe(x, alt(() => y) |
  303. * | ------- | ------- | -------------------- |
  304. * | none | none | none |
  305. * | some(a) | none | some(a) |
  306. * | none | some(b) | some(b) |
  307. * | some(a) | some(b) | some(a) |
  308. *
  309. * @example
  310. * import * as O from 'fp-ts/Option'
  311. * import { pipe } from 'fp-ts/function'
  312. *
  313. * assert.deepStrictEqual(
  314. * pipe(
  315. * O.none,
  316. * O.alt(() => O.none)
  317. * ),
  318. * O.none
  319. * )
  320. * assert.deepStrictEqual(
  321. * pipe(
  322. * O.some('a'),
  323. * O.alt<string>(() => O.none)
  324. * ),
  325. * O.some('a')
  326. * )
  327. * assert.deepStrictEqual(
  328. * pipe(
  329. * O.none,
  330. * O.alt(() => O.some('b'))
  331. * ),
  332. * O.some('b')
  333. * )
  334. * assert.deepStrictEqual(
  335. * pipe(
  336. * O.some('a'),
  337. * O.alt(() => O.some('b'))
  338. * ),
  339. * O.some('a')
  340. * )
  341. *
  342. * @category error handling
  343. * @since 2.0.0
  344. */
  345. export var alt = altW;
  346. /**
  347. * @category instances
  348. * @since 2.7.0
  349. */
  350. export var Alt = {
  351. URI: URI,
  352. map: _map,
  353. alt: _alt
  354. };
  355. /**
  356. * @since 2.7.0
  357. */
  358. export var zero = function () { return none; };
  359. /**
  360. * @category instances
  361. * @since 2.11.0
  362. */
  363. export var Zero = {
  364. URI: URI,
  365. zero: zero
  366. };
  367. /**
  368. * @category do notation
  369. * @since 2.11.0
  370. */
  371. export var guard = /*#__PURE__*/ guard_(Zero, Pointed);
  372. /**
  373. * @category instances
  374. * @since 2.7.0
  375. */
  376. export var Alternative = {
  377. URI: URI,
  378. map: _map,
  379. ap: _ap,
  380. of: of,
  381. alt: _alt,
  382. zero: zero
  383. };
  384. /**
  385. * @since 2.0.0
  386. */
  387. export var extend = function (f) { return function (wa) {
  388. return isNone(wa) ? none : some(f(wa));
  389. }; };
  390. /**
  391. * @category instances
  392. * @since 2.7.0
  393. */
  394. export var Extend = {
  395. URI: URI,
  396. map: _map,
  397. extend: _extend
  398. };
  399. /**
  400. * @category filtering
  401. * @since 2.0.0
  402. */
  403. export var compact = /*#__PURE__*/ chain(identity);
  404. var defaultSeparated = /*#__PURE__*/ separated(none, none);
  405. /**
  406. * @category filtering
  407. * @since 2.0.0
  408. */
  409. export var separate = function (ma) {
  410. return isNone(ma) ? defaultSeparated : separated(getLeft(ma.value), getRight(ma.value));
  411. };
  412. /**
  413. * @category instances
  414. * @since 2.7.0
  415. */
  416. export var Compactable = {
  417. URI: URI,
  418. compact: compact,
  419. separate: separate
  420. };
  421. /**
  422. * @category filtering
  423. * @since 2.0.0
  424. */
  425. export var filter = function (predicate) {
  426. return function (fa) {
  427. return isNone(fa) ? none : predicate(fa.value) ? fa : none;
  428. };
  429. };
  430. /**
  431. * @category filtering
  432. * @since 2.0.0
  433. */
  434. export var filterMap = function (f) { return function (fa) {
  435. return isNone(fa) ? none : f(fa.value);
  436. }; };
  437. /**
  438. * @category filtering
  439. * @since 2.0.0
  440. */
  441. export var partition = function (predicate) {
  442. return function (fa) {
  443. return separated(_filter(fa, not(predicate)), _filter(fa, predicate));
  444. };
  445. };
  446. /**
  447. * @category filtering
  448. * @since 2.0.0
  449. */
  450. export var partitionMap = function (f) { return flow(map(f), separate); };
  451. /**
  452. * @category instances
  453. * @since 2.7.0
  454. */
  455. export var Filterable = {
  456. URI: URI,
  457. map: _map,
  458. compact: compact,
  459. separate: separate,
  460. filter: _filter,
  461. filterMap: _filterMap,
  462. partition: _partition,
  463. partitionMap: _partitionMap
  464. };
  465. /**
  466. * @category traversing
  467. * @since 2.6.3
  468. */
  469. export var traverse = function (F) {
  470. return function (f) {
  471. return function (ta) {
  472. return isNone(ta) ? F.of(none) : F.map(f(ta.value), some);
  473. };
  474. };
  475. };
  476. /**
  477. * @category traversing
  478. * @since 2.6.3
  479. */
  480. export var sequence = function (F) {
  481. return function (ta) {
  482. return isNone(ta) ? F.of(none) : F.map(ta.value, some);
  483. };
  484. };
  485. /**
  486. * @category instances
  487. * @since 2.7.0
  488. */
  489. export var Traversable = {
  490. URI: URI,
  491. map: _map,
  492. reduce: _reduce,
  493. foldMap: _foldMap,
  494. reduceRight: _reduceRight,
  495. traverse: _traverse,
  496. sequence: sequence
  497. };
  498. var _wither = /*#__PURE__*/ witherDefault(Traversable, Compactable);
  499. var _wilt = /*#__PURE__*/ wiltDefault(Traversable, Compactable);
  500. /**
  501. * @category filtering
  502. * @since 2.6.5
  503. */
  504. export var wither = function (F) {
  505. var _witherF = _wither(F);
  506. return function (f) { return function (fa) { return _witherF(fa, f); }; };
  507. };
  508. /**
  509. * @category filtering
  510. * @since 2.6.5
  511. */
  512. export var wilt = function (F) {
  513. var _wiltF = _wilt(F);
  514. return function (f) { return function (fa) { return _wiltF(fa, f); }; };
  515. };
  516. /**
  517. * @category instances
  518. * @since 2.7.0
  519. */
  520. export var Witherable = {
  521. URI: URI,
  522. map: _map,
  523. reduce: _reduce,
  524. foldMap: _foldMap,
  525. reduceRight: _reduceRight,
  526. traverse: _traverse,
  527. sequence: sequence,
  528. compact: compact,
  529. separate: separate,
  530. filter: _filter,
  531. filterMap: _filterMap,
  532. partition: _partition,
  533. partitionMap: _partitionMap,
  534. wither: _wither,
  535. wilt: _wilt
  536. };
  537. /**
  538. * @since 2.7.0
  539. */
  540. export var throwError = function () { return none; };
  541. /**
  542. * @category instances
  543. * @since 2.7.0
  544. */
  545. export var MonadThrow = {
  546. URI: URI,
  547. map: _map,
  548. ap: _ap,
  549. of: of,
  550. chain: _chain,
  551. throwError: throwError
  552. };
  553. /**
  554. * Transforms an `Either` to an `Option` discarding the error.
  555. *
  556. * Alias of [getRight](#getright)
  557. *
  558. * @category conversions
  559. * @since 2.0.0
  560. */
  561. export var fromEither = getRight;
  562. /**
  563. * @category instances
  564. * @since 2.11.0
  565. */
  566. export var FromEither = {
  567. URI: URI,
  568. fromEither: fromEither
  569. };
  570. // -------------------------------------------------------------------------------------
  571. // refinements
  572. // -------------------------------------------------------------------------------------
  573. /**
  574. * Returns `true` if the option is an instance of `Some`, `false` otherwise.
  575. *
  576. * @example
  577. * import { some, none, isSome } from 'fp-ts/Option'
  578. *
  579. * assert.strictEqual(isSome(some(1)), true)
  580. * assert.strictEqual(isSome(none), false)
  581. *
  582. * @category refinements
  583. * @since 2.0.0
  584. */
  585. export var isSome = _.isSome;
  586. /**
  587. * Returns `true` if the option is `None`, `false` otherwise.
  588. *
  589. * @example
  590. * import { some, none, isNone } from 'fp-ts/Option'
  591. *
  592. * assert.strictEqual(isNone(some(1)), false)
  593. * assert.strictEqual(isNone(none), true)
  594. *
  595. * @category refinements
  596. * @since 2.0.0
  597. */
  598. export var isNone = function (fa) { return fa._tag === 'None'; };
  599. /**
  600. * Less strict version of [`match`](#match).
  601. *
  602. * The `W` suffix (short for **W**idening) means that the handler return types will be merged.
  603. *
  604. * @category pattern matching
  605. * @since 2.10.0
  606. */
  607. export var matchW = function (onNone, onSome) {
  608. return function (ma) {
  609. return isNone(ma) ? onNone() : onSome(ma.value);
  610. };
  611. };
  612. /**
  613. * Alias of [`matchW`](#matchw).
  614. *
  615. * @category pattern matching
  616. * @since 2.10.0
  617. */
  618. export var foldW = matchW;
  619. /**
  620. * Takes a (lazy) default value, a function, and an `Option` value, if the `Option` value is `None` the default value is
  621. * returned, otherwise the function is applied to the value inside the `Some` and the result is returned.
  622. *
  623. * @example
  624. * import { some, none, match } from 'fp-ts/Option'
  625. * import { pipe } from 'fp-ts/function'
  626. *
  627. * assert.strictEqual(
  628. * pipe(
  629. * some(1),
  630. * match(() => 'a none', a => `a some containing ${a}`)
  631. * ),
  632. * 'a some containing 1'
  633. * )
  634. *
  635. * assert.strictEqual(
  636. * pipe(
  637. * none,
  638. * match(() => 'a none', a => `a some containing ${a}`)
  639. * ),
  640. * 'a none'
  641. * )
  642. *
  643. * @category pattern matching
  644. * @since 2.10.0
  645. */
  646. export var match = matchW;
  647. /**
  648. * Alias of [`match`](#match).
  649. *
  650. * @category pattern matching
  651. * @since 2.0.0
  652. */
  653. export var fold = match;
  654. /**
  655. * Less strict version of [`getOrElse`](#getorelse).
  656. *
  657. * The `W` suffix (short for **W**idening) means that the handler return type will be merged.
  658. *
  659. * @category error handling
  660. * @since 2.6.0
  661. */
  662. export var getOrElseW = function (onNone) {
  663. return function (ma) {
  664. return isNone(ma) ? onNone() : ma.value;
  665. };
  666. };
  667. /**
  668. * Extracts the value out of the structure, if it exists. Otherwise returns the given default value
  669. *
  670. * @example
  671. * import { some, none, getOrElse } from 'fp-ts/Option'
  672. * import { pipe } from 'fp-ts/function'
  673. *
  674. * assert.strictEqual(
  675. * pipe(
  676. * some(1),
  677. * getOrElse(() => 0)
  678. * ),
  679. * 1
  680. * )
  681. * assert.strictEqual(
  682. * pipe(
  683. * none,
  684. * getOrElse(() => 0)
  685. * ),
  686. * 0
  687. * )
  688. *
  689. * @category error handling
  690. * @since 2.0.0
  691. */
  692. export var getOrElse = getOrElseW;
  693. /**
  694. * @category mapping
  695. * @since 2.10.0
  696. */
  697. export var flap = /*#__PURE__*/ flap_(Functor);
  698. /**
  699. * Combine two effectful actions, keeping only the result of the first.
  700. *
  701. * @since 2.0.0
  702. */
  703. export var apFirst = /*#__PURE__*/ apFirst_(Apply);
  704. /**
  705. * Combine two effectful actions, keeping only the result of the second.
  706. *
  707. * @since 2.0.0
  708. */
  709. export var apSecond = /*#__PURE__*/ apSecond_(Apply);
  710. /**
  711. * @category sequencing
  712. * @since 2.0.0
  713. */
  714. export var flatten = compact;
  715. /**
  716. * Composes computations in sequence, using the return value of one computation to determine the next computation and
  717. * keeping only the result of the first.
  718. *
  719. * @category sequencing
  720. * @since 2.0.0
  721. */
  722. export var chainFirst =
  723. /*#__PURE__*/ chainFirst_(Chain);
  724. /**
  725. * @since 2.0.0
  726. */
  727. export var duplicate = /*#__PURE__*/ extend(identity);
  728. /**
  729. * @category lifting
  730. * @since 2.11.0
  731. */
  732. export var fromEitherK = /*#__PURE__*/ fromEitherK_(FromEither);
  733. /**
  734. * @category sequencing
  735. * @since 2.11.0
  736. */
  737. export var chainEitherK =
  738. /*#__PURE__*/ chainEitherK_(FromEither, Chain);
  739. /**
  740. * @category sequencing
  741. * @since 2.12.0
  742. */
  743. export var chainFirstEitherK =
  744. /*#__PURE__*/ chainFirstEitherK_(FromEither, Chain);
  745. /**
  746. * Constructs a new `Option` from a nullable type. If the value is `null` or `undefined`, returns `None`, otherwise
  747. * returns the value wrapped in a `Some`.
  748. *
  749. * @example
  750. * import { none, some, fromNullable } from 'fp-ts/Option'
  751. *
  752. * assert.deepStrictEqual(fromNullable(undefined), none)
  753. * assert.deepStrictEqual(fromNullable(null), none)
  754. * assert.deepStrictEqual(fromNullable(1), some(1))
  755. *
  756. * @category conversions
  757. * @since 2.0.0
  758. */
  759. export var fromNullable = function (a) { return (a == null ? none : some(a)); };
  760. /**
  761. * Transforms an exception into an `Option`. If `f` throws, returns `None`, otherwise returns the output wrapped in a
  762. * `Some`.
  763. *
  764. * See also [`tryCatchK`](#trycatchk).
  765. *
  766. * @example
  767. * import { none, some, tryCatch } from 'fp-ts/Option'
  768. *
  769. * assert.deepStrictEqual(
  770. * tryCatch(() => {
  771. * throw new Error()
  772. * }),
  773. * none
  774. * )
  775. * assert.deepStrictEqual(tryCatch(() => 1), some(1))
  776. *
  777. * @category interop
  778. * @since 2.0.0
  779. */
  780. export var tryCatch = function (f) {
  781. try {
  782. return some(f());
  783. }
  784. catch (e) {
  785. return none;
  786. }
  787. };
  788. /**
  789. * Converts a function that may throw to one returning a `Option`.
  790. *
  791. * @category interop
  792. * @since 2.10.0
  793. */
  794. export var tryCatchK = function (f) {
  795. return function () {
  796. var a = [];
  797. for (var _i = 0; _i < arguments.length; _i++) {
  798. a[_i] = arguments[_i];
  799. }
  800. return tryCatch(function () { return f.apply(void 0, a); });
  801. };
  802. };
  803. /**
  804. * Returns a *smart constructor* from a function that returns a nullable value.
  805. *
  806. * @example
  807. * import { fromNullableK, none, some } from 'fp-ts/Option'
  808. *
  809. * const f = (s: string): number | undefined => {
  810. * const n = parseFloat(s)
  811. * return isNaN(n) ? undefined : n
  812. * }
  813. *
  814. * const g = fromNullableK(f)
  815. *
  816. * assert.deepStrictEqual(g('1'), some(1))
  817. * assert.deepStrictEqual(g('a'), none)
  818. *
  819. * @category lifting
  820. * @since 2.9.0
  821. */
  822. export var fromNullableK = function (f) { return flow(f, fromNullable); };
  823. /**
  824. * This is `chain` + `fromNullable`, useful when working with optional values.
  825. *
  826. * @example
  827. * import { some, none, fromNullable, chainNullableK } from 'fp-ts/Option'
  828. * import { pipe } from 'fp-ts/function'
  829. *
  830. * interface Employee {
  831. * readonly company?: {
  832. * readonly address?: {
  833. * readonly street?: {
  834. * readonly name?: string
  835. * }
  836. * }
  837. * }
  838. * }
  839. *
  840. * const employee1: Employee = { company: { address: { street: { name: 'high street' } } } }
  841. *
  842. * assert.deepStrictEqual(
  843. * pipe(
  844. * fromNullable(employee1.company),
  845. * chainNullableK(company => company.address),
  846. * chainNullableK(address => address.street),
  847. * chainNullableK(street => street.name)
  848. * ),
  849. * some('high street')
  850. * )
  851. *
  852. * const employee2: Employee = { company: { address: { street: {} } } }
  853. *
  854. * assert.deepStrictEqual(
  855. * pipe(
  856. * fromNullable(employee2.company),
  857. * chainNullableK(company => company.address),
  858. * chainNullableK(address => address.street),
  859. * chainNullableK(street => street.name)
  860. * ),
  861. * none
  862. * )
  863. *
  864. * @category sequencing
  865. * @since 2.9.0
  866. */
  867. export var chainNullableK = function (f) {
  868. return function (ma) {
  869. return isNone(ma) ? none : fromNullable(f(ma.value));
  870. };
  871. };
  872. /**
  873. * Extracts the value out of the structure, if it exists. Otherwise returns `null`.
  874. *
  875. * @example
  876. * import { some, none, toNullable } from 'fp-ts/Option'
  877. * import { pipe } from 'fp-ts/function'
  878. *
  879. * assert.strictEqual(
  880. * pipe(
  881. * some(1),
  882. * toNullable
  883. * ),
  884. * 1
  885. * )
  886. * assert.strictEqual(
  887. * pipe(
  888. * none,
  889. * toNullable
  890. * ),
  891. * null
  892. * )
  893. *
  894. * @category conversions
  895. * @since 2.0.0
  896. */
  897. export var toNullable = /*#__PURE__*/ match(constNull, identity);
  898. /**
  899. * Extracts the value out of the structure, if it exists. Otherwise returns `undefined`.
  900. *
  901. * @example
  902. * import { some, none, toUndefined } from 'fp-ts/Option'
  903. * import { pipe } from 'fp-ts/function'
  904. *
  905. * assert.strictEqual(
  906. * pipe(
  907. * some(1),
  908. * toUndefined
  909. * ),
  910. * 1
  911. * )
  912. * assert.strictEqual(
  913. * pipe(
  914. * none,
  915. * toUndefined
  916. * ),
  917. * undefined
  918. * )
  919. *
  920. * @category conversions
  921. * @since 2.0.0
  922. */
  923. export var toUndefined = /*#__PURE__*/ match(constUndefined, identity);
  924. export function elem(E) {
  925. return function (a, ma) {
  926. if (ma === undefined) {
  927. var elemE_1 = elem(E);
  928. return function (ma) { return elemE_1(a, ma); };
  929. }
  930. return isNone(ma) ? false : E.equals(a, ma.value);
  931. };
  932. }
  933. /**
  934. * Returns `true` if the predicate is satisfied by the wrapped value
  935. *
  936. * @example
  937. * import { some, none, exists } from 'fp-ts/Option'
  938. * import { pipe } from 'fp-ts/function'
  939. *
  940. * assert.strictEqual(
  941. * pipe(
  942. * some(1),
  943. * exists(n => n > 0)
  944. * ),
  945. * true
  946. * )
  947. * assert.strictEqual(
  948. * pipe(
  949. * some(1),
  950. * exists(n => n > 1)
  951. * ),
  952. * false
  953. * )
  954. * assert.strictEqual(
  955. * pipe(
  956. * none,
  957. * exists(n => n > 0)
  958. * ),
  959. * false
  960. * )
  961. *
  962. * @since 2.0.0
  963. */
  964. export var exists = function (predicate) {
  965. return function (ma) {
  966. return isNone(ma) ? false : predicate(ma.value);
  967. };
  968. };
  969. // -------------------------------------------------------------------------------------
  970. // do notation
  971. // -------------------------------------------------------------------------------------
  972. /**
  973. * @category do notation
  974. * @since 2.9.0
  975. */
  976. export var Do = /*#__PURE__*/ of(_.emptyRecord);
  977. /**
  978. * @category do notation
  979. * @since 2.8.0
  980. */
  981. export var bindTo = /*#__PURE__*/ bindTo_(Functor);
  982. var let_ = /*#__PURE__*/ let__(Functor);
  983. export {
  984. /**
  985. * @category do notation
  986. * @since 2.13.0
  987. */
  988. let_ as let };
  989. /**
  990. * @category do notation
  991. * @since 2.8.0
  992. */
  993. export var bind = /*#__PURE__*/ bind_(Chain);
  994. /**
  995. * @category do notation
  996. * @since 2.8.0
  997. */
  998. export var apS = /*#__PURE__*/ apS_(Apply);
  999. /**
  1000. * @since 2.11.0
  1001. */
  1002. export var ApT = /*#__PURE__*/ of(_.emptyReadonlyArray);
  1003. // -------------------------------------------------------------------------------------
  1004. // array utils
  1005. // -------------------------------------------------------------------------------------
  1006. /**
  1007. * Equivalent to `ReadonlyNonEmptyArray#traverseWithIndex(Applicative)`.
  1008. *
  1009. * @category traversing
  1010. * @since 2.11.0
  1011. */
  1012. export var traverseReadonlyNonEmptyArrayWithIndex = function (f) {
  1013. return function (as) {
  1014. var o = f(0, _.head(as));
  1015. if (isNone(o)) {
  1016. return none;
  1017. }
  1018. var out = [o.value];
  1019. for (var i = 1; i < as.length; i++) {
  1020. var o_1 = f(i, as[i]);
  1021. if (isNone(o_1)) {
  1022. return none;
  1023. }
  1024. out.push(o_1.value);
  1025. }
  1026. return some(out);
  1027. };
  1028. };
  1029. /**
  1030. * Equivalent to `ReadonlyArray#traverseWithIndex(Applicative)`.
  1031. *
  1032. * @category traversing
  1033. * @since 2.11.0
  1034. */
  1035. export var traverseReadonlyArrayWithIndex = function (f) {
  1036. var g = traverseReadonlyNonEmptyArrayWithIndex(f);
  1037. return function (as) { return (_.isNonEmpty(as) ? g(as) : ApT); };
  1038. };
  1039. /**
  1040. * Equivalent to `ReadonlyArray#traverseWithIndex(Applicative)`.
  1041. *
  1042. * @category traversing
  1043. * @since 2.9.0
  1044. */
  1045. export var traverseArrayWithIndex = traverseReadonlyArrayWithIndex;
  1046. /**
  1047. * Equivalent to `ReadonlyArray#traverse(Applicative)`.
  1048. *
  1049. * @category traversing
  1050. * @since 2.9.0
  1051. */
  1052. export var traverseArray = function (f) {
  1053. return traverseReadonlyArrayWithIndex(function (_, a) { return f(a); });
  1054. };
  1055. /**
  1056. * Equivalent to `ReadonlyArray#sequence(Applicative)`.
  1057. *
  1058. * @category traversing
  1059. * @since 2.9.0
  1060. */
  1061. export var sequenceArray =
  1062. /*#__PURE__*/ traverseArray(identity);
  1063. // -------------------------------------------------------------------------------------
  1064. // deprecated
  1065. // -------------------------------------------------------------------------------------
  1066. /**
  1067. * Use `Refinement` module instead.
  1068. *
  1069. * @category zone of death
  1070. * @since 2.0.0
  1071. * @deprecated
  1072. */
  1073. export function getRefinement(getOption) {
  1074. return function (a) { return isSome(getOption(a)); };
  1075. }
  1076. /**
  1077. * Use [`chainNullableK`](#chainnullablek) instead.
  1078. *
  1079. * @category zone of death
  1080. * @since 2.0.0
  1081. * @deprecated
  1082. */
  1083. export var mapNullable = chainNullableK;
  1084. /**
  1085. * This instance is deprecated, use small, specific instances instead.
  1086. * For example if a function needs a `Functor` instance, pass `O.Functor` instead of `O.option`
  1087. * (where `O` is from `import O from 'fp-ts/Option'`)
  1088. *
  1089. * @category zone of death
  1090. * @since 2.0.0
  1091. * @deprecated
  1092. */
  1093. export var option = {
  1094. URI: URI,
  1095. map: _map,
  1096. of: of,
  1097. ap: _ap,
  1098. chain: _chain,
  1099. reduce: _reduce,
  1100. foldMap: _foldMap,
  1101. reduceRight: _reduceRight,
  1102. traverse: _traverse,
  1103. sequence: sequence,
  1104. zero: zero,
  1105. alt: _alt,
  1106. extend: _extend,
  1107. compact: compact,
  1108. separate: separate,
  1109. filter: _filter,
  1110. filterMap: _filterMap,
  1111. partition: _partition,
  1112. partitionMap: _partitionMap,
  1113. wither: _wither,
  1114. wilt: _wilt,
  1115. throwError: throwError
  1116. };
  1117. /**
  1118. * Use [`getApplySemigroup`](./Apply.ts.html#getapplysemigroup) instead.
  1119. *
  1120. * @category zone of death
  1121. * @since 2.0.0
  1122. * @deprecated
  1123. */
  1124. export var getApplySemigroup = /*#__PURE__*/ getApplySemigroup_(Apply);
  1125. /**
  1126. * Use [`getApplicativeMonoid`](./Applicative.ts.html#getapplicativemonoid) instead.
  1127. *
  1128. * @category zone of death
  1129. * @since 2.0.0
  1130. * @deprecated
  1131. */
  1132. export var getApplyMonoid = /*#__PURE__*/ getApplicativeMonoid(Applicative);
  1133. /**
  1134. * Use
  1135. *
  1136. * ```ts
  1137. * import { first } from 'fp-ts/Semigroup'
  1138. * import { getMonoid } from 'fp-ts/Option'
  1139. *
  1140. * getMonoid(first())
  1141. * ```
  1142. *
  1143. * instead.
  1144. *
  1145. * Monoid returning the left-most non-`None` value
  1146. *
  1147. * | x | y | concat(x, y) |
  1148. * | ------- | ------- | ------------ |
  1149. * | none | none | none |
  1150. * | some(a) | none | some(a) |
  1151. * | none | some(b) | some(b) |
  1152. * | some(a) | some(b) | some(a) |
  1153. *
  1154. * @example
  1155. * import { getFirstMonoid, some, none } from 'fp-ts/Option'
  1156. *
  1157. * const M = getFirstMonoid<number>()
  1158. * assert.deepStrictEqual(M.concat(none, none), none)
  1159. * assert.deepStrictEqual(M.concat(some(1), none), some(1))
  1160. * assert.deepStrictEqual(M.concat(none, some(2)), some(2))
  1161. * assert.deepStrictEqual(M.concat(some(1), some(2)), some(1))
  1162. *
  1163. * @category zone of death
  1164. * @since 2.0.0
  1165. * @deprecated
  1166. */
  1167. export var getFirstMonoid = function () { return getMonoid(first()); };
  1168. /**
  1169. * Use
  1170. *
  1171. * ```ts
  1172. * import { last } from 'fp-ts/Semigroup'
  1173. * import { getMonoid } from 'fp-ts/Option'
  1174. *
  1175. * getMonoid(last())
  1176. * ```
  1177. *
  1178. * instead.
  1179. *
  1180. * Monoid returning the right-most non-`None` value
  1181. *
  1182. * | x | y | concat(x, y) |
  1183. * | ------- | ------- | ------------ |
  1184. * | none | none | none |
  1185. * | some(a) | none | some(a) |
  1186. * | none | some(b) | some(b) |
  1187. * | some(a) | some(b) | some(b) |
  1188. *
  1189. * @example
  1190. * import { getLastMonoid, some, none } from 'fp-ts/Option'
  1191. *
  1192. * const M = getLastMonoid<number>()
  1193. * assert.deepStrictEqual(M.concat(none, none), none)
  1194. * assert.deepStrictEqual(M.concat(some(1), none), some(1))
  1195. * assert.deepStrictEqual(M.concat(none, some(2)), some(2))
  1196. * assert.deepStrictEqual(M.concat(some(1), some(2)), some(2))
  1197. *
  1198. * @category zone of death
  1199. * @since 2.0.0
  1200. * @deprecated
  1201. */
  1202. export var getLastMonoid = function () { return getMonoid(last()); };