docs: ✏️ JSDoc blocks

Author: lrodrigues-newstore

packages/jest-either/README.md

@@ -12,125 +12,6 @@ Additional matchers for [Jest](https://jestjs.io) making it easier to test `Eith
 yarn add @pacote/jest-either
 ```
 
-## Usage
-
-```typescript
-import matchers from '@pacote/jest-either'
-
-expect.extend(matchers)
-```
-
-### `.toBeEither()`
-
-```typescript
-import { left, right } from 'fp-ts/lib/Either'
-
-test('passes when value is an Either', () => {
-  expect(left(true)).toBeEither()
-  expect(right(true)).toBeEither()
-})
-
-test('passes when value is not an Either', () => {
-  expect(undefined).not.toBeEither()
-})
-```
-
-### `.toBeRight()`
-
-```typescript
-import { left, right } from 'fp-ts/lib/Either'
-
-test('passes when Either is a right', () => {
-  const actual = right({ test: 'ok' })
-  expect(actual).toBeRight()
-})
-
-test('passes when Either is a left', () => {
-  const actual = left(Error())
-  expect(actual).not.toBeRight()
-})
-```
-
-### `.toBeLeft()`
-
-```typescript
-import { left, right } from 'fp-ts/lib/Either'
-
-test('passes when Either is a left', () => {
-  const actual = left(Error())
-  expect(actual).toBeLeft()
-})
-
-test('passes when Either is a right', () => {
-  const actual = right({ test: 'ok' })
-  expect(actual).not.toBeLeft()
-})
-```
-
-### `.toEqualRight(value)`
-
-```typescript
-import { right } from 'fp-ts/lib/Either'
-
-test('passes when right of Either equals a value', () => {
-  const actual = right({ test: 'ok' })
-  expect(actual).toEqualRight({ test: 'ok' })
-})
-
-test('passes when right of Either does not equal a value', () => {
-  const actual = right({ test: 'unexpected' })
-  expect(actual).not.toEqualRight({ test: 'ok' })
-})
-```
-
-### `.toEqualLeft(value)`
-
-```typescript
-import { left } from 'fp-ts/lib/Either'
-
-test('passes when left of Either equals a value', () => {
-  const actual = left(Error('message'))
-  expect(actual).toEqualLeft(Error('message'))
-})
-
-test('passes when left of Either does not equal a value', () => {
-  const actual = left(Error('unexpected'))
-  expect(actual).not.toEqualLeft(Error('message'))
-})
-```
-
-### `.toMatchRight(object)`
-
-```typescript
-import { right } from 'fp-ts/lib/Either'
-
-test('passes when right of Either matches an object', () => {
-  const actual = right({ test: 'ok', foo: 'bar' })
-  expect(actual).toMatchRight({ test: 'ok' })
-})
-
-test('passes when right of Either does not match an object', () => {
-  const actual = right({ test: 'unexpected', foo: 'bar' })
-  expect(actual).not.toMatchRight({ test: 'ok' })
-})
-```
-
-### `.toMatchLeft(object)`
-
-```typescript
-import { left } from 'fp-ts/lib/Either'
-
-test('passes when left of Either matches an object', () => {
-  const actual = left({ test: 'ok', foo: 'bar' })
-  expect(actual).toMatchLeft({ test: 'ok' })
-})
-
-test('passes when left of Either does not match an object', () => {
-  const actual = left({ test: 'unexpected', foo: 'bar' })
-  expect(actual).not.toMatchLeft({ test: 'ok' })
-})
-```
-
 ## License
 
 MIT © [Luís Rodrigues](https://goblindegook.com).

packages/jest-either/src/index.ts

@@ -1,20 +1,38 @@
+import type { MatchersObject } from './shared/types'
 import { toBeEither } from './toBeEither'
 import { toBeLeft } from './toBeLeft'
 import { toBeRight } from './toBeRight'
 import { toEqualLeft } from './toEqualLeft'
 import { toEqualRight } from './toEqualRight'
 import { toMatchLeft } from './toMatchLeft'
 import { toMatchRight } from './toMatchRight'
-import type { MatchersObject } from './shared/types'
 
-const matchers = {
+export { toBeEither } from './toBeEither'
+export { toBeLeft } from './toBeLeft'
+export { toBeRight } from './toBeRight'
+export { toEqualLeft } from './toEqualLeft'
+export { toEqualRight } from './toEqualRight'
+export { toMatchLeft } from './toMatchLeft'
+export { toMatchRight } from './toMatchRight'
+
+/**
+ * Collection of Jest matchers that assert on `Either` values.
+ *
+ * @returns Matchers ready to be passed into `expect.extend`.
+ *
+ * @example
+ * ```typescript
+ * import matchers from '@pacote/jest-either'
+ *
+ * expect.extend(matchers)
+ * ```
+ */
+export default {
   toBeEither,
   toBeLeft,
   toBeRight,
   toEqualLeft,
   toEqualRight,
   toMatchLeft,
   toMatchRight,
-}
-
-export default matchers as MatchersObject
+} as MatchersObject

packages/jest-either/src/toBeEither.ts

@@ -24,6 +24,23 @@ const failMessage = (actual: unknown) => () =>
     '',
   )}\n\nExpected Either, received:\n  ${printReceived(actual)}`
 
+/**
+ * Asserts that the received value is an `Either` instance.
+ *
+ * @example
+ * ```typescript
+ * import { left, right } from 'fp-ts/lib/Either'
+ *
+ * test('passes when value is an Either', () => {
+ *   expect(left(true)).toBeEither()
+ *   expect(right(true)).toBeEither()
+ * })
+ *
+ * test('passes when value is not an Either', () => {
+ *   expect(undefined).not.toBeEither()
+ * })
+ * ```
+ */
 export function toBeEither(actual: unknown): MatcherResult {
   const pass = isEither(actual)
   return {

packages/jest-either/src/toBeLeft.ts

@@ -32,6 +32,24 @@ const notEitherMessage = (actual: unknown) => () =>
     '',
   )}\n\nExpected value to be an Either.\n  Received: ${printReceived(actual)}`
 
+/**
+ * Asserts that the received `Either` is a `Left`.
+ *
+ * @example
+ * ```typescript
+ * import { left, right } from 'fp-ts/lib/Either'
+ *
+ * test('passes when Either is a left', () => {
+ *   const actual = left(Error())
+ *   expect(actual).toBeLeft()
+ * })
+ *
+ * test('passes when Either is a right', () => {
+ *   const actual = right({ test: 'ok' })
+ *   expect(actual).not.toBeLeft()
+ * })
+ * ```
+ */
 export function toBeLeft(actual: unknown): MatcherResult {
   if (!isEither(actual)) {
     return {

packages/jest-either/src/toBeRight.ts

@@ -32,6 +32,24 @@ const notEitherMessage = (actual: unknown) => () =>
     '',
   )}\n\nExpected value to be an Either.\n  Received: ${printReceived(actual)}`
 
+/**
+ * Asserts that the received `Either` is a `Right`.
+ *
+ * @example
+ * ```typescript
+ * import { left, right } from 'fp-ts/lib/Either'
+ *
+ * test('passes when Either is a right', () => {
+ *   const actual = right({ test: 'ok' })
+ *   expect(actual).toBeRight()
+ * })
+ *
+ * test('passes when Either is a left', () => {
+ *   const actual = left(Error())
+ *   expect(actual).not.toBeRight()
+ * })
+ * ```
+ */
 export function toBeRight(actual: unknown): MatcherResult {
   if (!isEither(actual)) {
     return {

packages/jest-either/src/toEqualLeft.ts

@@ -48,6 +48,29 @@ const notEitherMessage = (expected: unknown, actual: unknown) => () =>
     expected,
   )}\n  Received: ${printReceived(actual)}`
 
+/**
+ * Asserts that the left side of an `Either` equals an expected value or
+ * asymmetric matcher.
+ *
+ * @typeParam L Type of the expected left value.
+ *
+ * @param expected Value or asymmetric matcher that should equal the left side.
+ *
+ * @example
+ * ```typescript
+ * import { left } from 'fp-ts/lib/Either'
+ *
+ * test('passes when left of Either equals a value', () => {
+ *   const actual = left(Error('message'))
+ *   expect(actual).toEqualLeft(Error('message'))
+ * })
+ *
+ * test('passes when left of Either does not equal a value', () => {
+ *   const actual = left(Error('unexpected'))
+ *   expect(actual).not.toEqualLeft(Error('message'))
+ * })
+ * ```
+ */
 export function toEqualLeft<L>(
   actual: unknown,
   expected: L | AsymmetricMatcher,

packages/jest-either/src/toEqualRight.ts

@@ -47,6 +47,29 @@ const notEitherMessage = (expected: unknown, actual: unknown) => () =>
     expected,
   )}\n  Received: ${printReceived(actual)}`
 
+/**
+ * Asserts that the right side of an `Either` equals an expected value or
+ * asymmetric matcher.
+ *
+ * @typeParam R Type of the expected right value.
+ *
+ * @param expected Value or asymmetric matcher that should equal the right side.
+ *
+ * @example
+ * ```typescript
+ * import { right } from 'fp-ts/lib/Either'
+ *
+ * test('passes when right of Either equals a value', () => {
+ *   const actual = right({ test: 'ok' })
+ *   expect(actual).toEqualRight({ test: 'ok' })
+ * })
+ *
+ * test('passes when right of Either does not equal a value', () => {
+ *   const actual = right({ test: 'unexpected' })
+ *   expect(actual).not.toEqualRight({ test: 'ok' })
+ * })
+ * ```
+ */
 export function toEqualRight<R>(
   actual: unknown,
   expected: R | AsymmetricMatcher,

packages/jest-either/src/toMatchLeft.ts

@@ -56,6 +56,29 @@ const notEitherMessage = (expected: unknown, actual: unknown) => () =>
     expected,
   )}\n  Received: ${printReceived(actual)}`
 
+/**
+ * Asserts that the left side of an `Either` matches a value, partial object, or
+ * regular expression.
+ *
+ * @typeParam L Type of the left value contained in the `Either`.
+ *
+ * @param expected Pattern, partial object, or asymmetric matcher for the left.
+ *
+ * @example
+ * ```typescript
+ * import { left } from 'fp-ts/lib/Either'
+ *
+ * test('passes when left of Either matches an object', () => {
+ *   const actual = left({ test: 'ok', foo: 'bar' })
+ *   expect(actual).toMatchLeft({ test: 'ok' })
+ * })
+ *
+ * test('passes when left of Either does not match an object', () => {
+ *   const actual = left({ test: 'unexpected', foo: 'bar' })
+ *   expect(actual).not.toMatchLeft({ test: 'ok' })
+ * })
+ * ```
+ */
 export function toMatchLeft(
   actual: unknown,
   expected: RegExp | AsymmetricMatcher,

packages/jest-either/src/toMatchRight.ts

@@ -1,14 +1,14 @@
 import type { Either } from 'fp-ts/lib/Either'
 import { matcherHint, printExpected, printReceived } from 'jest-matcher-utils'
+import { isEither } from './shared/isEither'
 import {
   type AsymmetricMatcher,
   isAsymmetricMatcher,
   matchObject,
   matchString,
-  rightPredicate,
+  rightPredicate
 } from './shared/predicates'
 import { printReceivedRight } from './shared/print'
-import { isEither } from './shared/isEither'
 import type { MatcherResult } from './shared/types'
 
 declare global {
@@ -56,6 +56,29 @@ const notEitherMessage = (expected: unknown, actual: unknown) => () =>
     expected,
   )}\n  Received: ${printReceived(actual)}`
 
+/**
+ * Asserts that the right side of an `Either` matches a value, partial object,
+ * or regular expression.
+ *
+ * @typeParam R Type of the right value contained in the `Either`.
+ *
+ * @param expected Pattern, partial object, or asymmetric matcher for the right.
+ *
+ * @example
+ * ```typescript
+ * import { right } from 'fp-ts/lib/Either'
+ *
+ * test('passes when right of Either matches an object', () => {
+ *   const actual = right({ test: 'ok', foo: 'bar' })
+ *   expect(actual).toMatchRight({ test: 'ok' })
+ * })
+ *
+ * test('passes when right of Either does not match an object', () => {
+ *   const actual = right({ test: 'unexpected', foo: 'bar' })
+ *   expect(actual).not.toMatchRight({ test: 'ok' })
+ * })
+ * ```
+ */
 export function toMatchRight(
   actual: unknown,
   expected: RegExp | AsymmetricMatcher,