diff --git a/.changeset/green-years-tan.md b/.changeset/green-years-tan.md
new file mode 100644
index 00000000000..28941d6fa35
--- /dev/null
+++ b/.changeset/green-years-tan.md
@@ -0,0 +1,13 @@
+---
+"@effect/platform-node": patch
+"@effect/experimental": patch
+"@effect/typeclass": patch
+"@effect/platform": patch
+"@effect/printer": patch
+"effect": patch
+"@effect/sql-pg": patch
+"@effect/cli": patch
+"@effect/sql": patch
+---
+
+Wrap JSDoc @example tags with a TypeScript fence, closes #4002
diff --git a/README.md b/README.md
index fadad36110d..bb0c28dc2f9 100644
--- a/README.md
+++ b/README.md
@@ -110,9 +110,10 @@ Output:
Output:
-```
+````
*
* @example
+* ```ts
* import { Effect } from "effect"
*
* console.log(Effect.runSyncExit(Effect.succeed(1)))
@@ -122,8 +123,9 @@ Output:
* // _tag: "Success",
* // value: 1
* // }
+* ```
*
-```
+````
By using this utility, you can save time and maintain consistency in your JSDoc comments, especially for complex examples.
diff --git a/package.json b/package.json
index be1b3e7ee54..12aef4b9a51 100644
--- a/package.json
+++ b/package.json
@@ -46,7 +46,7 @@
"@changesets/cli": "^2.27.7",
"@edge-runtime/vm": "^4.0.0",
"@effect/build-utils": "^0.7.7",
- "@effect/docgen": "^0.4.4",
+ "@effect/docgen": "^0.5.1",
"@effect/dtslint": "^0.1.2",
"@effect/eslint-plugin": "^0.2.0",
"@effect/language-service": "^0.1.0",
diff --git a/packages/cli/src/Options.ts b/packages/cli/src/Options.ts
index 68f296ef52c..c95ec483aa4 100644
--- a/packages/cli/src/Options.ts
+++ b/packages/cli/src/Options.ts
@@ -154,12 +154,14 @@ export const boolean: (name: string, options?: Options.BooleanOptionsConfig) =>
* inputs. The input will be mapped to it's associated value during parsing.
*
* @example
+ * ```ts
* import * as Options from "@effect/cli/Options"
*
* export const animal: Options.Options<"dog" | "cat"> = Options.choice(
* "animal",
* ["dog", "cat"]
* )
+ * ```
*
* @since 1.0.0
* @category constructors
@@ -174,6 +176,7 @@ export const choice: >(
* inputs. The input will be mapped to it's associated value during parsing.
*
* @example
+ * ```ts
* import * as Options from "@effect/cli/Options"
* import * as Data from "effect/Data"
*
@@ -195,6 +198,7 @@ export const choice: >(
* ["dog", Dog()],
* ["cat", Cat()],
* ])
+ * ```
*
* @since 1.0.0
* @category constructors
diff --git a/packages/cli/src/Prompt.ts b/packages/cli/src/Prompt.ts
index 4f338168cfa..a015536b5eb 100644
--- a/packages/cli/src/Prompt.ts
+++ b/packages/cli/src/Prompt.ts
@@ -517,6 +517,7 @@ export declare namespace All {
* as an argument.
*
* @example
+ * ```ts
* import * as Prompt from "@effect/cli/Prompt"
* import * as NodeContext from "@effect/platform-node/NodeContext"
* import * as Runtime from "@effect/platform-node/NodeRuntime"
@@ -537,6 +538,7 @@ export declare namespace All {
* const allWithTuple = Prompt.all([username, password])
*
* const allWithRecord = Prompt.all({ username, password })
+ * ```
*
* @since 1.0.0
* @category collecting & elements
diff --git a/packages/effect/src/Array.ts b/packages/effect/src/Array.ts
index 36ecacce4b2..2802a3aff55 100644
--- a/packages/effect/src/Array.ts
+++ b/packages/effect/src/Array.ts
@@ -47,10 +47,12 @@ export type NonEmptyArray = [A, ...Array]
* Builds a `NonEmptyArray` from an non-empty collection of elements.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.make(1, 2, 3)
* assert.deepStrictEqual(result, [1, 2, 3])
+ * ```
*
* @category constructors
* @since 2.0.0
@@ -63,10 +65,12 @@ export const make = >(
* Creates a new `Array` of the specified length.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.allocate(3)
* assert.deepStrictEqual(result.length, 3)
+ * ```
*
* @category constructors
* @since 2.0.0
@@ -79,9 +83,11 @@ export const allocate = (n: number): Array => new Arra
* **Note**. `n` is normalized to an integer >= 1.
*
* @example
+ * ```ts
* import { makeBy } from "effect/Array"
*
* assert.deepStrictEqual(makeBy(5, n => n * 2), [0, 2, 4, 6, 8])
+ * ```
*
* @category constructors
* @since 2.0.0
@@ -99,9 +105,11 @@ export const makeBy = (n: number, f: (i: number) => A): NonEmptyArray => {
* Return a `NonEmptyArray` containing a range of integers, including both endpoints.
*
* @example
+ * ```ts
* import { range } from "effect/Array"
*
* assert.deepStrictEqual(range(1, 3), [1, 2, 3])
+ * ```
*
* @category constructors
* @since 2.0.0
@@ -115,9 +123,11 @@ export const range = (start: number, end: number): NonEmptyArray =>
* **Note**. `n` is normalized to an integer >= 1.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* assert.deepStrictEqual(Array.replicate("a", 3), ["a", "a", "a"])
+ * ```
*
* @category constructors
* @since 2.0.0
@@ -133,11 +143,13 @@ export const replicate: {
* Otherwise, it converts the iterable collection to an array.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const set = new Set([1, 2, 3])
* const result = Array.fromIterable(set)
* assert.deepStrictEqual(result, [1, 2, 3])
+ * ```
*
* @category constructors
* @since 2.0.0
@@ -149,11 +161,13 @@ export const fromIterable = (collection: Iterable): Array =>
* Creates a new `Array` from a value that might not be an iterable.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* assert.deepStrictEqual(Array.ensure("a"), ["a"])
* assert.deepStrictEqual(Array.ensure(["a"]), ["a"])
* assert.deepStrictEqual(Array.ensure(["a", "b", "c"]), ["a", "b", "c"])
+ * ```
*
* @category constructors
* @since 3.3.0
@@ -166,10 +180,12 @@ export const ensure = (self: ReadonlyArray | A): Array => Array.isArray
* @param self - The record to transform.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const x = { a: 1, b: 2, c: 3 }
* assert.deepStrictEqual(Array.fromRecord(x), [["a", 1], ["b", 2], ["c", 3]])
+ * ```
*
* @category conversions
* @since 2.0.0
@@ -180,10 +196,12 @@ export const fromRecord: (self: Readonly>) =>
* Converts an `Option` to an array.
*
* @example
+ * ```ts
* import { Array, Option } from "effect"
*
* assert.deepStrictEqual(Array.fromOption(Option.some(1)), [1])
* assert.deepStrictEqual(Array.fromOption(Option.none()), [])
+ * ```
*
* @category conversions
* @since 2.0.0
@@ -194,6 +212,7 @@ export const fromOption: (self: Option) => Array = O.toArray
* Matches the elements of an array, applying functions to cases of empty and non-empty arrays.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const match = Array.match({
@@ -202,6 +221,7 @@ export const fromOption: (self: Option) => Array = O.toArray
* })
* assert.deepStrictEqual(match([]), "empty")
* assert.deepStrictEqual(match([1, 2, 3]), "head: 1, tail: 2")
+ * ```
*
* @category pattern matching
* @since 2.0.0
@@ -232,6 +252,7 @@ export const match: {
* Matches the elements of an array from the left, applying functions to cases of empty and non-empty arrays.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const matchLeft = Array.matchLeft({
@@ -240,6 +261,7 @@ export const match: {
* })
* assert.deepStrictEqual(matchLeft([]), "empty")
* assert.deepStrictEqual(matchLeft([1, 2, 3]), "head: 1, tail: 2")
+ * ```
*
* @category pattern matching
* @since 2.0.0
@@ -270,6 +292,7 @@ export const matchLeft: {
* Matches the elements of an array from the right, applying functions to cases of empty and non-empty arrays.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const matchRight = Array.matchRight({
@@ -278,6 +301,7 @@ export const matchLeft: {
* })
* assert.deepStrictEqual(matchRight([]), "empty")
* assert.deepStrictEqual(matchRight([1, 2, 3]), "init: 2, last: 3")
+ * ```
*
* @category pattern matching
* @since 2.0.0
@@ -311,11 +335,13 @@ export const matchRight: {
* Prepend an element to the front of an `Iterable`, creating a new `NonEmptyArray`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const original = [2, 3, 4];
* const result = Array.prepend(original, 1);
* assert.deepStrictEqual(result, [1, 2, 3, 4]);
+ * ```
*
* @category concatenating
* @since 2.0.0
@@ -330,12 +356,14 @@ export const prepend: {
* If either array is non-empty, the result is also a non-empty array.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const prefix = [0, 1];
* const array = [2, 3];
* const result = Array.prependAll(array, prefix);
* assert.deepStrictEqual(result, [0, 1, 2, 3]);
+ * ```
*
* @category concatenating
* @since 2.0.0
@@ -356,11 +384,13 @@ export const prependAll: {
* Append an element to the end of an `Iterable`, creating a new `NonEmptyArray`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const original = [1, 2, 3];
* const result = Array.append(original, 4);
* assert.deepStrictEqual(result, [1, 2, 3, 4]);
+ * ```
*
* @category concatenating
* @since 2.0.0
@@ -395,6 +425,7 @@ export const appendAll: {
* a value through a series of transformations.
*
* @example
+ * ```ts
* import { Array } from "effect";
*
* const numbers = [1, 2, 3, 4]
@@ -406,6 +437,7 @@ export const appendAll: {
* // and adds each element of the array to this accumulator one by one,
* // keeping track of the cumulative sum after each addition.
* // Each of these sums is captured in the resulting array.
+ * ```
*
* @category folding
* @since 2.0.0
@@ -429,11 +461,13 @@ export const scan: {
* a value through a series of transformations.
*
* @example
+ * ```ts
* import { Array } from "effect";
*
* const numbers = [1, 2, 3, 4]
* const result = Array.scanRight(numbers, 0, (acc, value) => acc + value)
* assert.deepStrictEqual(result, [10, 9, 7, 4, 0])
+ * ```
*
* @category folding
* @since 2.0.0
@@ -457,10 +491,12 @@ export const scanRight: {
* @param self - The value to check.
*
* @example
+ * ```ts
* import { isArray } from "effect/Array"
*
* assert.deepStrictEqual(isArray(null), false);
* assert.deepStrictEqual(isArray([1, 2, 3]), true);
+ * ```
*
* @category guards
* @since 2.0.0
@@ -476,10 +512,12 @@ export const isArray: {
* @param self - The `Array` to check.
*
* @example
+ * ```ts
* import { isEmptyArray } from "effect/Array"
*
* assert.deepStrictEqual(isEmptyArray([]), true);
* assert.deepStrictEqual(isEmptyArray([1, 2, 3]), false);
+ * ```
*
* @category guards
* @since 2.0.0
@@ -492,10 +530,12 @@ export const isEmptyArray = (self: Array): self is [] => self.length === 0
* @param self - The `ReadonlyArray` to check.
*
* @example
+ * ```ts
* import { isEmptyReadonlyArray } from "effect/Array"
*
* assert.deepStrictEqual(isEmptyReadonlyArray([]), true);
* assert.deepStrictEqual(isEmptyReadonlyArray([1, 2, 3]), false);
+ * ```
*
* @category guards
* @since 2.0.0
@@ -510,10 +550,12 @@ export const isEmptyReadonlyArray: (self: ReadonlyArray) => self is readon
* @param self - The `Array` to check.
*
* @example
+ * ```ts
* import { isNonEmptyArray } from "effect/Array"
*
* assert.deepStrictEqual(isNonEmptyArray([]), false);
* assert.deepStrictEqual(isNonEmptyArray([1, 2, 3]), true);
+ * ```
*
* @category guards
* @since 2.0.0
@@ -528,10 +570,12 @@ export const isNonEmptyArray: (self: Array) => self is NonEmptyArray =
* @param self - The `ReadonlyArray` to check.
*
* @example
+ * ```ts
* import { isNonEmptyReadonlyArray } from "effect/Array"
*
* assert.deepStrictEqual(isNonEmptyReadonlyArray([]), false);
* assert.deepStrictEqual(isNonEmptyReadonlyArray([1, 2, 3]), true);
+ * ```
*
* @category guards
* @since 2.0.0
@@ -586,10 +630,12 @@ export const unsafeGet: {
* Return a tuple containing the first element, and a new `Array` of the remaining elements, if any.
*
* @example
+ * ```ts
* import { Array } from "effect";
*
* const result = Array.unprepend([1, 2, 3, 4])
* assert.deepStrictEqual(result, [1, [2, 3, 4]])
+ * ```
*
* @category splitting
* @since 2.0.0
@@ -602,10 +648,12 @@ export const unprepend = (
* Return a tuple containing a copy of the `NonEmptyReadonlyArray` without its last element, and that last element.
*
* @example
+ * ```ts
* import { Array } from "effect";
*
* const result = Array.unappend([1, 2, 3, 4])
* assert.deepStrictEqual(result, [[1, 2, 3], 4])
+ * ```
*
* @category splitting
* @since 2.0.0
@@ -626,10 +674,12 @@ export const head: (self: ReadonlyArray) => Option = get(0)
* Get the first element of a non empty array.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.headNonEmpty([1, 2, 3, 4])
* assert.deepStrictEqual(result, 1)
+ * ```
*
* @category getters
* @since 2.0.0
@@ -649,10 +699,12 @@ export const last = (self: ReadonlyArray): Option =>
* Get the last element of a non empty array.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.lastNonEmpty([1, 2, 3, 4])
* assert.deepStrictEqual(result, 4)
+ * ```
*
* @category getters
* @since 2.0.0
@@ -674,10 +726,12 @@ export const tail = (self: Iterable): Option> => {
* Get all but the first element of a `NonEmptyReadonlyArray`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.tailNonEmpty([1, 2, 3, 4])
* assert.deepStrictEqual(result, [2, 3, 4])
+ * ```
*
* @category getters
* @since 2.0.0
@@ -699,10 +753,12 @@ export const init = (self: Iterable): Option> => {
* Get all but the last element of a non empty array, creating a new array.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.initNonEmpty([1, 2, 3, 4])
* assert.deepStrictEqual(result, [1, 2, 3])
+ * ```
*
* @category getters
* @since 2.0.0
@@ -715,11 +771,13 @@ export const initNonEmpty = (self: NonEmptyReadonlyArray): Array => sel
* **Note**. `n` is normalized to a non negative integer.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
* const result = Array.take(numbers, 3)
* assert.deepStrictEqual(result, [1, 2, 3])
+ * ```
*
* @category getters
* @since 2.0.0
@@ -738,11 +796,13 @@ export const take: {
* **Note**. `n` is normalized to a non negative integer.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
* const result = Array.takeRight(numbers, 3)
* assert.deepStrictEqual(result, [3, 4, 5])
+ * ```
*
* @category getters
* @since 2.0.0
@@ -760,6 +820,7 @@ export const takeRight: {
* Calculate the longest initial subarray for which all element satisfy the specified predicate, creating a new `Array`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 3, 2, 4, 1, 2]
@@ -771,6 +832,7 @@ export const takeRight: {
* // - The next element (`3`) is also less than `4`, so it adds `3`.
* // - The next element (`2`) is again less than `4`, so it adds `2`.
* // - The function then encounters `4`, which is not less than `4`. At this point, it stops checking further elements and finalizes the result.
+ * ```
*
* @category getters
* @since 2.0.0
@@ -835,11 +897,13 @@ export const span: {
* **Note**. `n` is normalized to a non negative integer.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
* const result = Array.drop(numbers, 2)
* assert.deepStrictEqual(result, [3, 4, 5])
+ * ```
*
* @category getters
* @since 2.0.0
@@ -858,11 +922,13 @@ export const drop: {
* **Note**. `n` is normalized to a non negative integer.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
* const result = Array.dropRight(numbers, 2)
* assert.deepStrictEqual(result, [1, 2, 3])
+ * ```
*
* @category getters
* @since 2.0.0
@@ -879,11 +945,13 @@ export const dropRight: {
* Remove the longest initial subarray for which all element satisfy the specified predicate, creating a new `Array`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
* const result = Array.dropWhile(numbers, x => x < 4)
* assert.deepStrictEqual(result, [4, 5])
+ * ```
*
* @category getters
* @since 2.0.0
@@ -901,11 +969,13 @@ export const dropWhile: {
* Return the first index for which a predicate holds.
*
* @example
+ * ```ts
* import { Array, Option } from "effect"
*
* const numbers = [5, 3, 8, 9]
* const result = Array.findFirstIndex(numbers, x => x > 5)
* assert.deepStrictEqual(result, Option.some(2))
+ * ```
*
* @category elements
* @since 2.0.0
@@ -928,11 +998,13 @@ export const findFirstIndex: {
* Return the last index for which a predicate holds.
*
* @example
+ * ```ts
* import { Array, Option } from "effect"
*
* const numbers = [1, 3, 8, 9]
* const result = Array.findLastIndex(numbers, x => x < 5)
* assert.deepStrictEqual(result, Option.some(1))
+ * ```
*
* @category elements
* @since 2.0.0
@@ -955,11 +1027,13 @@ export const findLastIndex: {
* predicate, or `None` if no such element exists.
*
* @example
+ * ```ts
* import { Array, Option } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
* const result = Array.findFirst(numbers, x => x > 3)
* assert.deepStrictEqual(result, Option.some(4))
+ * ```
*
* @category elements
* @since 2.0.0
@@ -978,11 +1052,13 @@ export const findFirst: {
* Returns an `Option` containing the found element, or `Option.none` if no element matches.
*
* @example
+ * ```ts
* import { Array, Option } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
* const result = Array.findLast(numbers, n => n % 2 === 0)
* assert.deepStrictEqual(result, Option.some(4))
+ * ```
*
* @category elements
* @since 2.0.0
@@ -1020,11 +1096,13 @@ export const findLast: {
* or return `None` if the index is out of bounds.
*
* @example
+ * ```ts
* import { Array, Option } from "effect"
*
* const letters = ['a', 'b', 'c', 'e']
* const result = Array.insertAt(letters, 3, 'd')
* assert.deepStrictEqual(result, Option.some(['a', 'b', 'c', 'd', 'e']))
+ * ```
*
* @since 2.0.0
*/
@@ -1046,11 +1124,13 @@ export const insertAt: {
* or return a copy of the input if the index is out of bounds.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const letters = ['a', 'b', 'c', 'd']
* const result = Array.replace(letters, 1, 'z')
* assert.deepStrictEqual(result, ['a', 'z', 'c', 'd'])
+ * ```
*
* @since 2.0.0
*/
@@ -1072,11 +1152,13 @@ export const replace: {
* Replaces an element in an array with the given value, returning an option of the updated array.
*
* @example
+ * ```ts
* import { Array, Option } from "effect"
*
* const numbers = [1, 2, 3]
* const result = Array.replaceOption(numbers, 1, 4)
* assert.deepStrictEqual(result, Option.some([1, 4, 3]))
+ * ```
*
* @since 2.0.0
*/
@@ -1100,11 +1182,13 @@ export const replaceOption: {
* or return a copy of the input if the index is out of bounds.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4]
* const result = Array.modify(numbers, 2, (n) => n * 2)
* assert.deepStrictEqual(result, [1, 2, 6, 4])
+ * ```
*
* @since 2.0.0
*/
@@ -1129,6 +1213,7 @@ export const modify: {
* or return `None` if the index is out of bounds.
*
* @example
+ * ```ts
* import { Array, Option } from "effect"
*
* const numbers = [1, 2, 3, 4]
@@ -1137,6 +1222,7 @@ export const modify: {
*
* const outOfBoundsResult = Array.modifyOption(numbers, 5, (n) => n * 2)
* assert.deepStrictEqual(outOfBoundsResult, Option.none())
+ * ```
*
* @since 2.0.0
*/
@@ -1166,6 +1252,7 @@ export const modifyOption: {
* or return a copy of the input if the index is out of bounds.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4]
@@ -1174,6 +1261,7 @@ export const modifyOption: {
*
* const outOfBoundsResult = Array.remove(numbers, 5)
* assert.deepStrictEqual(outOfBoundsResult, [1, 2, 3, 4])
+ * ```
*
* @since 2.0.0
*/
@@ -1193,11 +1281,13 @@ export const remove: {
* Reverse an `Iterable`, creating a new `Array`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4]
* const result = Array.reverse(numbers)
* assert.deepStrictEqual(result, [4, 3, 2, 1])
+ * ```
*
* @category elements
* @since 2.0.0
@@ -1232,6 +1322,7 @@ export const sort: {
* order defines how those values should be sorted.
*
* @example
+ * ```ts
* import { Array, Order } from "effect"
*
* const strings = ["aaa", "b", "cc"]
@@ -1242,6 +1333,7 @@ export const sort: {
* // The array of strings is sorted based on their lengths. The mapping function `(s) => s.length`
* // converts each string into its length, and the `Order.number` specifies that the lengths should
* // be sorted in ascending order.
+ * ```
*
* @since 2.0.0
* @category elements
@@ -1265,6 +1357,7 @@ export const sortWith: {
* second order if the first comparison is equal, and so on.
*
* @example
+ * ```ts
* import { Array, Order } from "effect"
*
* const users = [
@@ -1287,6 +1380,7 @@ export const sortWith: {
* // Explanation:
* // The array of users is sorted first by age in ascending order. When ages are equal,
* // the users are further sorted by name in ascending order.
+ * ```
*
* @category sorting
* @since 2.0.0
@@ -1312,12 +1406,14 @@ export const sortBy = | NonEmptyReadonlyArray>(
* longer `Iterable` are discarded.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const array1 = [1, 2, 3]
* const array2 = ['a', 'b']
* const result = Array.zip(array1, array2)
* assert.deepStrictEqual(result, [[1, 'a'], [2, 'b']])
+ * ```
*
* @category zipping
* @since 2.0.0
@@ -1337,12 +1433,14 @@ export const zip: {
* input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const array1 = [1, 2, 3]
* const array2 = [4, 5, 6]
* const result = Array.zipWith(array1, array2, (a, b) => a + b)
* assert.deepStrictEqual(result, [5, 7, 9])
+ * ```
*
* @category zipping
* @since 2.0.0
@@ -1370,10 +1468,12 @@ export const zipWith: {
* This function is the inverse of `zip`. Takes an `Iterable` of pairs and return two corresponding `Array`s.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.unzip([[1, "a"], [2, "b"], [3, "c"]])
* assert.deepStrictEqual(result, [[1, 2, 3], ['a', 'b', 'c']])
+ * ```
*
* @since 2.0.0
*/
@@ -1400,11 +1500,13 @@ export const unzip: | NonEmptyReadonlyA
* If the input is a non-empty array, the result is also a non-empty array.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3]
* const result = Array.intersperse(numbers, 0)
* assert.deepStrictEqual(result, [1, 0, 2, 0, 3])
+ * ```
*
* @since 2.0.0
*/
@@ -1434,10 +1536,12 @@ export const intersperse: {
* Apply a function to the head, creating a new `NonEmptyReadonlyArray`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.modifyNonEmptyHead([1, 2, 3], n => n * 10)
* assert.deepStrictEqual(result, [10, 2, 3])
+ * ```
*
* @since 2.0.0
*/
@@ -1456,10 +1560,12 @@ export const modifyNonEmptyHead: {
* Change the head, creating a new `NonEmptyReadonlyArray`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.setNonEmptyHead([1, 2, 3], 10)
* assert.deepStrictEqual(result, [10, 2, 3])
+ * ```
*
* @since 2.0.0
*/
@@ -1475,10 +1581,12 @@ export const setNonEmptyHead: {
* Apply a function to the last element, creating a new `NonEmptyReadonlyArray`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.modifyNonEmptyLast([1, 2, 3], n => n * 2)
* assert.deepStrictEqual(result, [1, 2, 6])
+ * ```
*
* @since 2.0.0
*/
@@ -1495,10 +1603,12 @@ export const modifyNonEmptyLast: {
* Change the last element, creating a new `NonEmptyReadonlyArray`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.setNonEmptyLast([1, 2, 3], 4)
* assert.deepStrictEqual(result, [1, 2, 4])
+ * ```
*
* @since 2.0.0
*/
@@ -1515,11 +1625,13 @@ export const setNonEmptyLast: {
* If the input is a non-empty array, the result is also a non-empty array.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const letters = ['a', 'b', 'c', 'd']
* const result = Array.rotate(letters, 2)
* assert.deepStrictEqual(result, ['c', 'd', 'a', 'b'])
+ * ```
*
* @since 2.0.0
*/
@@ -1549,6 +1661,7 @@ export const rotate: {
* Returns a function that checks if a `ReadonlyArray` contains a given value using a provided `isEquivalent` function.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4]
@@ -1556,6 +1669,7 @@ export const rotate: {
* const containsNumber = Array.containsWith(isEquivalent)
* const result = containsNumber(3)(numbers)
* assert.deepStrictEqual(result, true)
+ * ```
*
* @category elements
* @since 2.0.0
@@ -1579,11 +1693,13 @@ const _equivalence = Equal.equivalence()
* Returns a function that checks if a `ReadonlyArray` contains a given value using the default `Equivalence`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const letters = ['a', 'b', 'c', 'd']
* const result = Array.contains('c')(letters)
* assert.deepStrictEqual(result, true)
+ * ```
*
* @category elements
* @since 2.0.0
@@ -1599,6 +1715,7 @@ export const contains: {
* value and the rest of the `Array`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
@@ -1609,6 +1726,7 @@ export const contains: {
* // The `chopFunction` takes the first element of the array, doubles it, and then returns it along with the rest of the array.
* // The `chop` function applies this `chopFunction` recursively to the input array `[1, 2, 3, 4, 5]`,
* // resulting in a new array `[2, 4, 6, 8, 10]`.
+ * ```
*
* @since 2.0.0
*/
@@ -1648,11 +1766,13 @@ export const chop: {
* The value of `n` can be `0`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
* const result = Array.splitAt(numbers, 3)
* assert.deepStrictEqual(result, [[1, 2, 3], [4, 5]])
+ * ```
*
* @category splitting
* @since 2.0.0
@@ -1677,10 +1797,12 @@ export const splitAt: {
* The value of `n` must be `>= 1`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.splitNonEmptyAt(["a", "b", "c", "d", "e"], 3)
* assert.deepStrictEqual(result, [["a", "b", "c"], ["d", "e"]])
+ * ```
*
* @category splitting
* @since 2.0.0
@@ -1699,11 +1821,13 @@ export const splitNonEmptyAt: {
* Splits this iterable into `n` equally sized arrays.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4, 5, 6, 7, 8]
* const result = Array.split(numbers, 3)
* assert.deepStrictEqual(result, [[1, 2, 3], [4, 5, 6], [7, 8]])
+ * ```
*
* @since 2.0.0
* @category splitting
@@ -1721,11 +1845,13 @@ export const split: {
* Returns a tuple containing two arrays: the first one is before the match, and the second one is from the match onward.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
* const result = Array.splitWhere(numbers, n => n > 3)
* assert.deepStrictEqual(result, [[1, 2, 3], [4, 5]])
+ * ```
*
* @category splitting
* @since 2.0.0
@@ -1745,11 +1871,13 @@ export const splitWhere: {
* Copies an array.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3]
* const copy = Array.copy(numbers)
* assert.deepStrictEqual(copy, [1, 2, 3])
+ * ```
*
* @since 2.0.0
*/
@@ -1765,11 +1893,13 @@ export const copy: {
* If `n` is less than or equal to 0, the returned array will be an empty array.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const arr = [1, 2, 3]
* const result = Array.pad(arr, 6, 0)
* assert.deepStrictEqual(result, [1, 2, 3, 0, 0, 0])
+ * ```
*
* @since 3.8.4
*/
@@ -1803,6 +1933,7 @@ export const pad: {
* whenever `n` evenly divides the length of `self`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3, 4, 5]
@@ -1814,6 +1945,7 @@ export const pad: {
* // It splits the array into chunks of length 2. Since the array length is not evenly divisible by 2,
* // the last chunk contains the remaining elements.
* // The result is `[[1, 2], [3, 4], [5]]`.
+ * ```
*
* @category splitting
* @since 2.0.0
@@ -1838,10 +1970,12 @@ export const chunksOf: {
* Group equal, consecutive elements of a `NonEmptyReadonlyArray` into `NonEmptyArray`s using the provided `isEquivalent` function.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.groupWith(["a", "a", "b", "b", "b", "c", "a"], (x, y) => x === y)
* assert.deepStrictEqual(result, [["a", "a"], ["b", "b", "b"], ["c"], ["a"]])
+ * ```
*
* @category grouping
* @since 2.0.0
@@ -1872,10 +2006,12 @@ export const groupWith: {
* Group equal, consecutive elements of a `NonEmptyReadonlyArray` into `NonEmptyArray`s.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const result = Array.group([1, 1, 2, 2, 2, 3, 1])
* assert.deepStrictEqual(result, [[1, 1], [2, 2, 2], [3], [1]])
+ * ```
*
* @category grouping
* @since 2.0.0
@@ -1889,6 +2025,7 @@ export const group: (self: NonEmptyReadonlyArray) => NonEmptyArray(self: NonEmptyReadonlyArray) => NonEmptyArray a === b)
* assert.deepStrictEqual(union, [1, 2, 3])
+ * ```
*
* @since 2.0.0
*/
@@ -1975,12 +2115,14 @@ export const unionWith: {
* Creates a union of two arrays, removing duplicates.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const array1 = [1, 2]
* const array2 = [2, 3]
* const result = Array.union(array1, array2)
* assert.deepStrictEqual(result, [1, 2, 3])
+ * ```
*
* @since 2.0.0
*/
@@ -2000,6 +2142,7 @@ export const union: {
* The order and references of result values are determined by the first `Iterable`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const array1 = [{ id: 1 }, { id: 2 }, { id: 3 }]
@@ -2007,6 +2150,7 @@ export const union: {
* const isEquivalent = (a: { id: number }, b: { id: number }) => a.id === b.id
* const result = Array.intersectionWith(isEquivalent)(array2)(array1)
* assert.deepStrictEqual(result, [{ id: 1 }, { id: 3 }])
+ * ```
*
* @since 2.0.0
*/
@@ -2026,12 +2170,14 @@ export const intersectionWith = (isEquivalent: (self: A, that: A) => boolean)
* The order and references of result values are determined by the first `Iterable`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const array1 = [1, 2, 3]
* const array2 = [3, 4, 1]
* const result = Array.intersection(array1, array2)
* assert.deepStrictEqual(result, [1, 3])
+ * ```
*
* @since 2.0.0
*/
@@ -2045,12 +2191,14 @@ export const intersection: {
* The order and references of result values are determined by the first `Iterable`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const array1 = [1, 2, 3]
* const array2 = [2, 3, 4]
* const difference = Array.differenceWith((a, b) => a === b)(array1, array2)
* assert.deepStrictEqual(difference, [1])
+ * ```
*
* @since 2.0.0
*/
@@ -2070,12 +2218,14 @@ export const differenceWith = (isEquivalent: (self: A, that: A) => boolean):
* The order and references of result values are determined by the first `Iterable`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const array1 = [1, 2, 3]
* const array2 = [2, 3, 4]
* const difference = Array.difference(array1, array2)
* assert.deepStrictEqual(difference, [1])
+ * ```
*
* @since 2.0.0
*/
@@ -2192,12 +2342,14 @@ export const flatMap: {
* arrays is collapsed into a single, flat array.
*
* @example
+ * ```ts
* import { Array } from "effect";
*
* const nestedArrays = [[1, 2], [], [3, 4], [], [5, 6]]
* const result = Array.flatten(nestedArrays)
*
* assert.deepStrictEqual(result, [1, 2, 3, 4, 5, 6]);
+ * ```
*
* @category sequencing
* @since 2.0.0
@@ -2211,6 +2363,7 @@ export const flatten: >>(self: S) =>
* This method combines filtering and mapping functionalities, allowing transformations and filtering of elements based on a single function pass.
*
* @example
+ * ```ts
* import { Array, Option } from "effect";
*
* const data = [1, 2, 3, 4, 5];
@@ -2218,6 +2371,7 @@ export const flatten: >>(self: S) =>
* const result = Array.filterMap(data, evenSquares);
*
* assert.deepStrictEqual(result, [4, 16]);
+ * ```
*
* @category filtering
* @since 2.0.0
@@ -2246,6 +2400,7 @@ export const filterMap: {
* This is useful when you need to transform an array but only up to the point where a certain condition holds true.
*
* @example
+ * ```ts
* import { Array, Option } from "effect";
*
* const data = [2, 4, 5];
@@ -2253,6 +2408,7 @@ export const filterMap: {
* const result = Array.filterMapWhile(data, toSquareTillOdd);
*
* assert.deepStrictEqual(result, [4, 16]);
+ * ```
*
* @category filtering
* @since 2.0.0
@@ -2282,6 +2438,7 @@ export const filterMapWhile: {
* into successes and failures.
*
* @example
+ * ```ts
* import { Array, Either } from "effect";
*
* const data = [1, 2, 3, 4, 5]
@@ -2294,6 +2451,7 @@ export const filterMapWhile: {
* [1, 3, 5],
* [2, 4]
* ])
+ * ```
*
* @category filtering
* @since 2.0.0
@@ -2323,12 +2481,14 @@ export const partitionMap: {
* Retrieves the `Some` values from an `Iterable` of `Option`s, collecting them into an array.
*
* @example
+ * ```ts
* import { Array, Option } from "effect"
*
* assert.deepStrictEqual(
* Array.getSomes([Option.some(1), Option.none(), Option.some(2)]),
* [1, 2]
* )
+ * ```
*
* @category filtering
* @since 2.0.0
@@ -2342,12 +2502,14 @@ export const getSomes: >, X = any>(
* Retrieves the `Left` values from an `Iterable` of `Either`s, collecting them into an array.
*
* @example
+ * ```ts
* import { Array, Either } from "effect"
*
* assert.deepStrictEqual(
* Array.getLefts([Either.right(1), Either.left("err"), Either.right(2)]),
* ["err"]
* )
+ * ```
*
* @category filtering
* @since 2.0.0
@@ -2367,12 +2529,14 @@ export const getLefts = >>(self: T): Array n % 2 === 0)
* assert.deepStrictEqual(result, [[1, 3], [2, 4]])
+ * ```
*
* @category filtering
* @since 2.0.0
@@ -2471,11 +2637,13 @@ export const separate: >>(
* Reduces an array from the left.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3]
* const result = Array.reduce(numbers, 0, (acc, n) => acc + n)
* assert.deepStrictEqual(result, 6)
+ * ```
*
* @category folding
* @since 2.0.0
@@ -2493,11 +2661,13 @@ export const reduce: {
* Reduces an array from the right.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3]
* const result = Array.reduceRight(numbers, 0, (acc, n) => acc + n)
* assert.deepStrictEqual(result, 6)
+ * ```
*
* @category folding
* @since 2.0.0
@@ -2515,12 +2685,14 @@ export const reduceRight: {
* Lifts a predicate into an array.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const isEven = (n: number) => n % 2 === 0
* const to = Array.liftPredicate(isEven)
* assert.deepStrictEqual(to(1), [])
* assert.deepStrictEqual(to(2), [2])
+ * ```
*
* @category lifting
* @since 2.0.0
@@ -2558,6 +2730,7 @@ export const liftNullable = , B>(
* Maps over an array and flattens the result, removing null and undefined values.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3]
@@ -2568,6 +2741,7 @@ export const liftNullable = , B>(
* // The array of numbers [1, 2, 3] is mapped with a function that returns null for even numbers
* // and the number itself for odd numbers. The resulting array [1, null, 3] is then flattened
* // to remove null values, resulting in [1, 3].
+ * ```
*
* @category sequencing
* @since 2.0.0
@@ -2587,6 +2761,7 @@ export const flatMapNullable: {
* If the `Either` is a right, it returns an array with the right value.
*
* @example
+ * ```ts
* import { Array, Either } from "effect"
*
* const parseNumber = (s: string): Either.Either =>
@@ -2604,6 +2779,7 @@ export const flatMapNullable: {
* // The function parseNumber is lifted to return an array.
* // When parsing "42", it returns an Either.left with the number 42, resulting in [42].
* // When parsing "not a number", it returns an Either.right with an error, resulting in an empty array [].
+ * ```
*
* @category lifting
* @since 2.0.0
@@ -2656,6 +2832,7 @@ export const some: {
* Extends an array with a function that maps each subarray to a value.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3]
@@ -2667,6 +2844,7 @@ export const some: {
* // The subarrays are: [1, 2, 3], [2, 3], [3].
* // The lengths are: 3, 2, 1.
* // Therefore, the result is [3, 2, 1].
+ * ```
*
* @since 2.0.0
*/
@@ -2682,10 +2860,12 @@ export const extend: {
* Finds the minimum element in an array based on a comparator.
*
* @example
+ * ```ts
* import { Array, Order } from "effect"
*
* const min = Array.min([3, 1, 2], Order.number)
* assert.deepStrictEqual(min, 1)
+ * ```
*
* @since 2.0.0
*/
@@ -2698,10 +2878,12 @@ export const min: {
* Finds the maximum element in an array based on a comparator.
*
* @example
+ * ```ts
* import { Array, Order } from "effect"
*
* const max = Array.max([3, 1, 2], Order.number)
* assert.deepStrictEqual(max, 3)
+ * ```
*
* @since 2.0.0
*/
@@ -2741,12 +2923,14 @@ export const getOrder: (O: Order.Order) => Order.Order> =
* Creates an equivalence relation for arrays.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers1 = [1, 2, 3]
* const numbers2 = [1, 2, 3]
* const eq = Array.getEquivalence((a, b) => a === b)
* assert.deepStrictEqual(eq(numbers1, numbers2), true)
+ * ```
*
* @category instances
* @since 2.0.0
@@ -2759,10 +2943,12 @@ export const getEquivalence: (
* Performs a side-effect for each element of the `Iterable`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3]
* Array.forEach(numbers, n => console.log(n)) // 1, 2, 3
+ * ```
*
* @since 2.0.0
*/
@@ -2776,11 +2962,13 @@ export const forEach: {
* preserving the order of the first occurrence of each element.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 2, 3, 3, 3]
* const unique = Array.dedupeWith(numbers, (a, b) => a === b)
* assert.deepStrictEqual(unique, [1, 2, 3])
+ * ```
*
* @since 2.0.0
*/
@@ -2823,11 +3011,13 @@ export const dedupe = | NonEmptyReadonlyArray>(
* Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 1, 2, 2, 3, 3]
* const unique = Array.dedupeAdjacentWith(numbers, (a, b) => a === b)
* assert.deepStrictEqual(unique, [1, 2, 3])
+ * ```
*
* @since 2.0.0
*/
@@ -2850,11 +3040,13 @@ export const dedupeAdjacentWith: {
* Deduplicates adjacent elements that are identical.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 1, 2, 2, 3, 3]
* const unique = Array.dedupeAdjacent(numbers)
* assert.deepStrictEqual(unique, [1, 2, 3])
+ * ```
*
* @since 2.0.0
*/
@@ -2864,11 +3056,13 @@ export const dedupeAdjacent: (self: Iterable) => Array = dedupeAdjacent
* Joins the elements together with "sep" in the middle.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const strings = ["a", "b", "c"]
* const joined = Array.join(strings, "-")
* assert.deepStrictEqual(joined, "a-b-c")
+ * ```
*
* @since 2.0.0
* @category folding
@@ -2882,11 +3076,13 @@ export const join: {
* Statefully maps over the chunk, producing new elements of type `B`.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const numbers = [1, 2, 3]
* const result = Array.mapAccum(numbers, 0, (acc, n) => [acc + n, acc + n])
* assert.deepStrictEqual(result, [6, [1, 3, 6]])
+ * ```
*
* @since 2.0.0
* @category folding
@@ -2921,12 +3117,14 @@ export const mapAccum: {
* Zips this chunk crosswise with the specified chunk using the specified combiner.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const array1 = [1, 2]
* const array2 = ["a", "b"]
* const product = Array.cartesianWith(array1, array2, (a, b) => `${a}-${b}`)
* assert.deepStrictEqual(product, ["1-a", "1-b", "2-a", "2-b"])
+ * ```
*
* @since 2.0.0
* @category elements
@@ -2944,12 +3142,14 @@ export const cartesianWith: {
* Zips this chunk crosswise with the specified chunk.
*
* @example
+ * ```ts
* import { Array } from "effect"
*
* const array1 = [1, 2]
* const array2 = ["a", "b"]
* const product = Array.cartesian(array1, array2)
* assert.deepStrictEqual(product, [[1, "a"], [1, "b"], [2, "a"], [2, "b"]])
+ * ```
*
* @since 2.0.0
* @category elements
@@ -2985,6 +3185,7 @@ export const cartesian: {
* @see {@link let_ let}
*
* @example
+ * ```ts
* import { Array as Arr, pipe } from "effect"
* const doResult = pipe(
* Arr.Do,
@@ -3005,6 +3206,7 @@ export const cartesian: {
* if(_x < _y) result.push([_x, _y] as const)
* }
* }
+ * ```
*
* @category do notation
* @since 3.2.0
@@ -3030,6 +3232,7 @@ export const Do: ReadonlyArray<{}> = of({})
* @see {@link let_ let}
*
* @example
+ * ```ts
* import { Array as Arr, pipe } from "effect"
* const doResult = pipe(
* Arr.Do,
@@ -3050,6 +3253,7 @@ export const Do: ReadonlyArray<{}> = of({})
* if(_x < _y) result.push([_x, _y] as const)
* }
* }
+ * ```
*
* @category do notation
* @since 3.2.0
@@ -3087,6 +3291,7 @@ export const bind: {
* @see {@link let_ let}
*
* @example
+ * ```ts
* import { Array as Arr, pipe } from "effect"
* const doResult = pipe(
* Arr.Do,
@@ -3107,6 +3312,7 @@ export const bind: {
* if(_x < _y) result.push([_x, _y] as const)
* }
* }
+ * ```
*
* @category do notation
* @since 3.2.0
@@ -3148,6 +3354,7 @@ export {
* @see {@link Do}
*
* @example
+ * ```ts
* import { Array as Arr, pipe } from "effect"
* const doResult = pipe(
* Arr.Do,
@@ -3169,6 +3376,7 @@ export {
* }
* }
*
+ * ```
* @category do notation
* @since 3.2.0
*/
diff --git a/packages/effect/src/BigDecimal.ts b/packages/effect/src/BigDecimal.ts
index 360dd6de230..72347aed704 100644
--- a/packages/effect/src/BigDecimal.ts
+++ b/packages/effect/src/BigDecimal.ts
@@ -134,10 +134,12 @@ const zero = unsafeMakeNormalized(bigint0, 0)
* @param self - The `BigDecimal` to normalize.
*
* @example
+ * ```ts
* import { normalize, make, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(normalize(unsafeFromString("123.00000")), normalize(make(123n, 0)))
* assert.deepStrictEqual(normalize(unsafeFromString("12300000")), normalize(make(123n, -5)))
+ * ```
*
* @since 2.0.0
* @category scaling
@@ -205,9 +207,11 @@ export const scale: {
* @param that - The second operand.
*
* @example
+ * ```ts
* import { sum, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(sum(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("5"))
+ * ```
*
* @since 2.0.0
* @category math
@@ -242,9 +246,11 @@ export const sum: {
* @param that - The second operand.
*
* @example
+ * ```ts
* import { multiply, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(multiply(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("6"))
+ * ```
*
* @since 2.0.0
* @category math
@@ -267,9 +273,11 @@ export const multiply: {
* @param that - The second operand.
*
* @example
+ * ```ts
* import { subtract, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(subtract(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("-1"))
+ * ```
*
* @since 2.0.0
* @category math
@@ -377,11 +385,13 @@ export const roundTerminal = (n: bigint): bigint => {
* @param that - The divisor operand.
*
* @example
+ * ```ts
* import { BigDecimal, Option } from "effect"
*
* assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("3")), Option.some(BigDecimal.unsafeFromString("2")))
* assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("4")), Option.some(BigDecimal.unsafeFromString("1.5")))
* assert.deepStrictEqual(BigDecimal.divide(BigDecimal.unsafeFromString("6"), BigDecimal.unsafeFromString("0")), Option.none())
+ * ```
*
* @since 2.0.0
* @category math
@@ -418,10 +428,12 @@ export const divide: {
* @param that - The divisor operand.as
*
* @example
+ * ```ts
* import { unsafeDivide, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("3")), unsafeFromString("2"))
* assert.deepStrictEqual(unsafeDivide(unsafeFromString("6"), unsafeFromString("4")), unsafeFromString("1.5"))
+ * ```
*
* @since 2.0.0
* @category math
@@ -473,11 +485,13 @@ export const Order: order.Order = order.make((self, that) => {
* @param that - The second argument.
*
* @example
+ * ```ts
* import { lessThan, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(lessThan(unsafeFromString("2"), unsafeFromString("3")), true)
* assert.deepStrictEqual(lessThan(unsafeFromString("3"), unsafeFromString("3")), false)
* assert.deepStrictEqual(lessThan(unsafeFromString("4"), unsafeFromString("3")), false)
+ * ```
*
* @since 2.0.0
* @category predicates
@@ -494,11 +508,13 @@ export const lessThan: {
* @param that - The second `BigDecimal` to compare with.
*
* @example
+ * ```ts
* import { lessThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), true)
* assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
* assert.deepStrictEqual(lessThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), false)
+ * ```
*
* @since 2.0.0
* @category predicates
@@ -515,11 +531,13 @@ export const lessThanOrEqualTo: {
* @param that - The second argument.
*
* @example
+ * ```ts
* import { greaterThan, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(greaterThan(unsafeFromString("2"), unsafeFromString("3")), false)
* assert.deepStrictEqual(greaterThan(unsafeFromString("3"), unsafeFromString("3")), false)
* assert.deepStrictEqual(greaterThan(unsafeFromString("4"), unsafeFromString("3")), true)
+ * ```
*
* @since 2.0.0
* @category predicates
@@ -536,11 +554,13 @@ export const greaterThan: {
* @param that - The second `BigDecimal` to compare with.
*
* @example
+ * ```ts
* import { greaterThanOrEqualTo, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("2"), unsafeFromString("3")), false)
* assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("3"), unsafeFromString("3")), true)
* assert.deepStrictEqual(greaterThanOrEqualTo(unsafeFromString("4"), unsafeFromString("3")), true)
+ * ```
*
* @since 2.0.0
* @category predicates
@@ -558,6 +578,7 @@ export const greaterThanOrEqualTo: {
* @param maximum - The `maximum` value to check.
*
* @example
+ * ```ts
* import { BigDecimal } from "effect"
*
* const between = BigDecimal.between({
@@ -568,6 +589,7 @@ export const greaterThanOrEqualTo: {
* assert.deepStrictEqual(between(BigDecimal.unsafeFromString("3")), true)
* assert.deepStrictEqual(between(BigDecimal.unsafeFromString("0")), false)
* assert.deepStrictEqual(between(BigDecimal.unsafeFromString("6")), false)
+ * ```
*
* @since 2.0.0
* @category predicates
@@ -595,6 +617,7 @@ export const between: {
* @param maximum - The upper end of the range.
*
* @example
+ * ```ts
* import { BigDecimal } from "effect"
*
* const clamp = BigDecimal.clamp({
@@ -605,6 +628,7 @@ export const between: {
* assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("3")), BigDecimal.unsafeFromString("3"))
* assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("0")), BigDecimal.unsafeFromString("1"))
* assert.deepStrictEqual(clamp(BigDecimal.unsafeFromString("6")), BigDecimal.unsafeFromString("5"))
+ * ```
*
* @since 2.0.0
* @category math
@@ -627,9 +651,11 @@ export const clamp: {
* @param that - The second `BigDecimal`.
*
* @example
+ * ```ts
* import { min, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(min(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("2"))
+ * ```
*
* @since 2.0.0
* @category math
@@ -646,9 +672,11 @@ export const min: {
* @param that - The second `BigDecimal`.
*
* @example
+ * ```ts
* import { max, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(max(unsafeFromString("2"), unsafeFromString("3")), unsafeFromString("3"))
+ * ```
*
* @since 2.0.0
* @category math
@@ -664,11 +692,13 @@ export const max: {
* @param n - The `BigDecimal` to determine the sign of.
*
* @example
+ * ```ts
* import { sign, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(sign(unsafeFromString("-5")), -1)
* assert.deepStrictEqual(sign(unsafeFromString("0")), 0)
* assert.deepStrictEqual(sign(unsafeFromString("5")), 1)
+ * ```
*
* @since 2.0.0
* @category math
@@ -681,11 +711,13 @@ export const sign = (n: BigDecimal): Ordering => n.value === bigint0 ? 0 : n.val
* @param n - The `BigDecimal` to determine the absolute value of.
*
* @example
+ * ```ts
* import { abs, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(abs(unsafeFromString("-5")), unsafeFromString("5"))
* assert.deepStrictEqual(abs(unsafeFromString("0")), unsafeFromString("0"))
* assert.deepStrictEqual(abs(unsafeFromString("5")), unsafeFromString("5"))
+ * ```
*
* @since 2.0.0
* @category math
@@ -698,10 +730,12 @@ export const abs = (n: BigDecimal): BigDecimal => n.value < bigint0 ? make(-n.va
* @param n - The `BigDecimal` to negate.
*
* @example
+ * ```ts
* import { negate, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(negate(unsafeFromString("3")), unsafeFromString("-3"))
* assert.deepStrictEqual(negate(unsafeFromString("-6")), unsafeFromString("6"))
+ * ```
*
* @since 2.0.0
* @category math
@@ -717,11 +751,13 @@ export const negate = (n: BigDecimal): BigDecimal => make(-n.value, n.scale)
* @param divisor - The divisor.
*
* @example
+ * ```ts
* import { BigDecimal, Option } from "effect"
*
* assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("2"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
* assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("3"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("1")))
* assert.deepStrictEqual(BigDecimal.remainder(BigDecimal.unsafeFromString("-4"), BigDecimal.unsafeFromString("2")), Option.some(BigDecimal.unsafeFromString("0")))
+ * ```
*
* @since 2.0.0
* @category math
@@ -747,11 +783,13 @@ export const remainder: {
* @param divisor - The divisor.
*
* @example
+ * ```ts
* import { unsafeRemainder, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(unsafeRemainder(unsafeFromString("2"), unsafeFromString("2")), unsafeFromString("0"))
* assert.deepStrictEqual(unsafeRemainder(unsafeFromString("3"), unsafeFromString("2")), unsafeFromString("1"))
* assert.deepStrictEqual(unsafeRemainder(unsafeFromString("-4"), unsafeFromString("2")), unsafeFromString("0"))
+ * ```
*
* @since 2.0.0
* @category math
@@ -814,10 +852,12 @@ export const fromBigInt = (n: bigint): BigDecimal => make(n, 0)
* @param value - The `number` value to create a `BigDecimal` from.
*
* @example
+ * ```ts
* import { fromNumber, make } from "effect/BigDecimal"
*
* assert.deepStrictEqual(fromNumber(123), make(123n, 0))
* assert.deepStrictEqual(fromNumber(123.456), make(123456n, 3))
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -833,11 +873,13 @@ export const fromNumber = (n: number): BigDecimal => {
* @param s - The `string` to parse.
*
* @example
+ * ```ts
* import { BigDecimal, Option } from "effect"
*
* assert.deepStrictEqual(BigDecimal.fromString("123"), Option.some(BigDecimal.make(123n, 0)))
* assert.deepStrictEqual(BigDecimal.fromString("123.456"), Option.some(BigDecimal.make(123456n, 3)))
* assert.deepStrictEqual(BigDecimal.fromString("123.abc"), Option.none())
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -875,11 +917,13 @@ export const fromString = (s: string): Option.Option => {
* @param s - The `string` to parse.
*
* @example
+ * ```ts
* import { unsafeFromString, make } from "effect/BigDecimal"
*
* assert.deepStrictEqual(unsafeFromString("123"), make(123n, 0))
* assert.deepStrictEqual(unsafeFromString("123.456"), make(123456n, 3))
* assert.throws(() => unsafeFromString("123.abc"))
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -893,11 +937,13 @@ export const unsafeFromString = (s: string): BigDecimal =>
* @param normalized - The `BigDecimal` to format.
*
* @example
+ * ```ts
* import { format, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(format(unsafeFromString("-5")), "-5")
* assert.deepStrictEqual(format(unsafeFromString("123.456")), "123.456")
* assert.deepStrictEqual(format(unsafeFromString("-0.00000123")), "-0.00000123")
+ * ```
*
* @since 2.0.0
* @category conversions
@@ -936,9 +982,11 @@ export const format = (n: BigDecimal): string => {
* @param n - The `BigDecimal` to convert.
*
* @example
+ * ```ts
* import { unsafeToNumber, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(unsafeToNumber(unsafeFromString("123.456")), 123.456)
+ * ```
*
* @since 2.0.0
* @category conversions
@@ -951,11 +999,13 @@ export const unsafeToNumber = (n: BigDecimal): number => Number(format(n))
* @param n - The `BigDecimal` to check.
*
* @example
+ * ```ts
* import { isInteger, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(isInteger(unsafeFromString("0")), true)
* assert.deepStrictEqual(isInteger(unsafeFromString("1")), true)
* assert.deepStrictEqual(isInteger(unsafeFromString("1.1")), false)
+ * ```
*
* @since 2.0.0
* @category predicates
@@ -968,10 +1018,12 @@ export const isInteger = (n: BigDecimal): boolean => normalize(n).scale <= 0
* @param n - The `BigDecimal` to check.
*
* @example
+ * ```ts
* import { isZero, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(isZero(unsafeFromString("0")), true)
* assert.deepStrictEqual(isZero(unsafeFromString("1")), false)
+ * ```
*
* @since 2.0.0
* @category predicates
@@ -984,11 +1036,13 @@ export const isZero = (n: BigDecimal): boolean => n.value === bigint0
* @param n - The `BigDecimal` to check.
*
* @example
+ * ```ts
* import { isNegative, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(isNegative(unsafeFromString("-1")), true)
* assert.deepStrictEqual(isNegative(unsafeFromString("0")), false)
* assert.deepStrictEqual(isNegative(unsafeFromString("1")), false)
+ * ```
*
* @since 2.0.0
* @category predicates
@@ -1001,11 +1055,13 @@ export const isNegative = (n: BigDecimal): boolean => n.value < bigint0
* @param n - The `BigDecimal` to check.
*
* @example
+ * ```ts
* import { isPositive, unsafeFromString } from "effect/BigDecimal"
*
* assert.deepStrictEqual(isPositive(unsafeFromString("-1")), false)
* assert.deepStrictEqual(isPositive(unsafeFromString("0")), false)
* assert.deepStrictEqual(isPositive(unsafeFromString("1")), true)
+ * ```
*
* @since 2.0.0
* @category predicates
diff --git a/packages/effect/src/BigInt.ts b/packages/effect/src/BigInt.ts
index 6b6ea3d2bb4..f0b82e02705 100644
--- a/packages/effect/src/BigInt.ts
+++ b/packages/effect/src/BigInt.ts
@@ -23,10 +23,12 @@ const bigint2 = BigInt(2)
* @param input - The value to test.
*
* @example
+ * ```ts
* import { isBigInt } from "effect/BigInt"
*
* assert.deepStrictEqual(isBigInt(1n), true)
* assert.deepStrictEqual(isBigInt(1), false)
+ * ```
*
* @category guards
* @since 2.0.0
@@ -40,9 +42,11 @@ export const isBigInt: (u: unknown) => u is bigint = predicate.isBigInt
* @param that - The second operand.
*
* @example
+ * ```ts
* import { sum } from "effect/BigInt"
*
* assert.deepStrictEqual(sum(2n, 3n), 5n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -59,9 +63,11 @@ export const sum: {
* @param that - The second operand.
*
* @example
+ * ```ts
* import { multiply } from "effect/BigInt"
*
* assert.deepStrictEqual(multiply(2n, 3n), 6n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -78,9 +84,11 @@ export const multiply: {
* @param that - The second operand.
*
* @example
+ * ```ts
* import { subtract } from "effect/BigInt"
*
* assert.deepStrictEqual(subtract(2n, 3n), -1n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -102,10 +110,12 @@ export const subtract: {
* @param that - The divisor operand.
*
* @example
+ * ```ts
* import { BigInt, Option } from "effect"
*
* assert.deepStrictEqual(BigInt.divide(6n, 3n), Option.some(2n))
* assert.deepStrictEqual(BigInt.divide(6n, 0n), Option.none())
+ * ```
*
* @category math
* @since 2.0.0
@@ -130,10 +140,12 @@ export const divide: {
* @param that - The divisor operand.
*
* @example
+ * ```ts
* import { unsafeDivide } from "effect/BigInt"
*
* assert.deepStrictEqual(unsafeDivide(6n, 3n), 2n)
* assert.deepStrictEqual(unsafeDivide(6n, 4n), 1n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -149,9 +161,11 @@ export const unsafeDivide: {
* @param n - A `bigint` to be incremented.
*
* @example
+ * ```ts
* import { increment } from "effect/BigInt"
*
* assert.deepStrictEqual(increment(2n), 3n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -164,9 +178,11 @@ export const increment = (n: bigint): bigint => n + bigint1
* @param n - A `bigint` to be decremented.
*
* @example
+ * ```ts
* import { decrement } from "effect/BigInt"
*
* assert.deepStrictEqual(decrement(3n), 2n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -192,11 +208,13 @@ export const Order: order.Order = order.bigint
* @param that - The second argument.
*
* @example
+ * ```ts
* import { lessThan } from "effect/BigInt"
*
* assert.deepStrictEqual(lessThan(2n, 3n), true)
* assert.deepStrictEqual(lessThan(3n, 3n), false)
* assert.deepStrictEqual(lessThan(4n, 3n), false)
+ * ```
*
* @category predicates
* @since 2.0.0
@@ -213,11 +231,13 @@ export const lessThan: {
* @param that - The second `bigint` to compare with.
*
* @example
+ * ```ts
* import { lessThanOrEqualTo } from "effect/BigInt"
*
* assert.deepStrictEqual(lessThanOrEqualTo(2n, 3n), true)
* assert.deepStrictEqual(lessThanOrEqualTo(3n, 3n), true)
* assert.deepStrictEqual(lessThanOrEqualTo(4n, 3n), false)
+ * ```
*
* @category predicates
* @since 2.0.0
@@ -234,11 +254,13 @@ export const lessThanOrEqualTo: {
* @param that - The second argument.
*
* @example
+ * ```ts
* import { greaterThan } from "effect/BigInt"
*
* assert.deepStrictEqual(greaterThan(2n, 3n), false)
* assert.deepStrictEqual(greaterThan(3n, 3n), false)
* assert.deepStrictEqual(greaterThan(4n, 3n), true)
+ * ```
*
* @category predicates
* @since 2.0.0
@@ -255,11 +277,13 @@ export const greaterThan: {
* @param that - The second `bigint` to compare with.
*
* @example
+ * ```ts
* import { greaterThanOrEqualTo } from "effect/BigInt"
*
* assert.deepStrictEqual(greaterThanOrEqualTo(2n, 3n), false)
* assert.deepStrictEqual(greaterThanOrEqualTo(3n, 3n), true)
* assert.deepStrictEqual(greaterThanOrEqualTo(4n, 3n), true)
+ * ```
*
* @category predicates
* @since 2.0.0
@@ -277,6 +301,7 @@ export const greaterThanOrEqualTo: {
* @param maximum - The `maximum` value to check.
*
* @example
+ * ```ts
* import { BigInt } from "effect"
*
* const between = BigInt.between({ minimum: 0n, maximum: 5n })
@@ -284,6 +309,7 @@ export const greaterThanOrEqualTo: {
* assert.deepStrictEqual(between(3n), true)
* assert.deepStrictEqual(between(-1n), false)
* assert.deepStrictEqual(between(6n), false)
+ * ```
*
* @category predicates
* @since 2.0.0
@@ -311,6 +337,7 @@ export const between: {
* @param maximum - The upper end of the range.
*
* @example
+ * ```ts
* import { BigInt } from "effect"
*
* const clamp = BigInt.clamp({ minimum: 1n, maximum: 5n })
@@ -318,6 +345,7 @@ export const between: {
* assert.equal(clamp(3n), 3n)
* assert.equal(clamp(0n), 1n)
* assert.equal(clamp(6n), 5n)
+ * ```
*
* @since 2.0.0
*/
@@ -339,9 +367,11 @@ export const clamp: {
* @param that - The second `bigint`.
*
* @example
+ * ```ts
* import { min } from "effect/BigInt"
*
* assert.deepStrictEqual(min(2n, 3n), 2n)
+ * ```
*
* @since 2.0.0
*/
@@ -357,9 +387,11 @@ export const min: {
* @param that - The second `bigint`.
*
* @example
+ * ```ts
* import { max } from "effect/BigInt"
*
* assert.deepStrictEqual(max(2n, 3n), 3n)
+ * ```
*
* @since 2.0.0
*/
@@ -374,11 +406,13 @@ export const max: {
* @param n - The `bigint` to determine the sign of.
*
* @example
+ * ```ts
* import { sign } from "effect/BigInt"
*
* assert.deepStrictEqual(sign(-5n), -1)
* assert.deepStrictEqual(sign(0n), 0)
* assert.deepStrictEqual(sign(5n), 1)
+ * ```
*
* @category math
* @since 2.0.0
@@ -391,11 +425,13 @@ export const sign = (n: bigint): Ordering => Order(n, bigint0)
* @param n - The `bigint` to determine the absolute value of.
*
* @example
+ * ```ts
* import { abs } from "effect/BigInt"
*
* assert.deepStrictEqual(abs(-5n), 5n)
* assert.deepStrictEqual(abs(0n), 0n)
* assert.deepStrictEqual(abs(5n), 5n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -409,11 +445,13 @@ export const abs = (n: bigint): bigint => (n < bigint0 ? -n : n)
* @param b - The second `bigint`.
*
* @example
+ * ```ts
* import { gcd } from "effect/BigInt"
*
* assert.deepStrictEqual(gcd(2n, 3n), 1n)
* assert.deepStrictEqual(gcd(2n, 4n), 2n)
* assert.deepStrictEqual(gcd(16n, 24n), 8n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -437,11 +475,13 @@ export const gcd: {
* @param b - The second `bigint`.
*
* @example
+ * ```ts
* import { lcm } from "effect/BigInt"
*
* assert.deepStrictEqual(lcm(2n, 3n), 6n)
* assert.deepStrictEqual(lcm(2n, 4n), 4n)
* assert.deepStrictEqual(lcm(16n, 24n), 48n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -457,11 +497,13 @@ export const lcm: {
* @param n - The `bigint` to determine the square root of.
*
* @example
+ * ```ts
* import { unsafeSqrt } from "effect/BigInt"
*
* assert.deepStrictEqual(unsafeSqrt(4n), 2n)
* assert.deepStrictEqual(unsafeSqrt(9n), 3n)
* assert.deepStrictEqual(unsafeSqrt(16n), 4n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -486,12 +528,14 @@ export const unsafeSqrt = (n: bigint): bigint => {
* @param n - The `bigint` to determine the square root of.
*
* @example
+ * ```ts
* import { BigInt, Option } from "effect"
*
* assert.deepStrictEqual(BigInt.sqrt(4n), Option.some(2n))
* assert.deepStrictEqual(BigInt.sqrt(9n), Option.some(3n))
* assert.deepStrictEqual(BigInt.sqrt(16n), Option.some(4n))
* assert.deepStrictEqual(BigInt.sqrt(-1n), Option.none())
+ * ```
*
* @category math
* @since 2.0.0
@@ -505,9 +549,11 @@ export const sqrt = (n: bigint): Option.Option =>
* @param collection - The collection of `bigint`s to sum.
*
* @example
+ * ```ts
* import { sumAll } from "effect/BigInt"
*
* assert.deepStrictEqual(sumAll([2n, 3n, 4n]), 9n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -526,9 +572,11 @@ export const sumAll = (collection: Iterable): bigint => {
* @param collection - The collection of `bigint`s to multiply.
*
* @example
+ * ```ts
* import { multiplyAll } from "effect/BigInt"
*
* assert.deepStrictEqual(multiplyAll([2n, 3n, 4n]), 24n)
+ * ```
*
* @category math
* @since 2.0.0
@@ -554,11 +602,13 @@ export const multiplyAll = (collection: Iterable): bigint => {
* @param b - The `bigint` to be converted to a `number`.
*
* @example
+ * ```ts
* import { BigInt as BI, Option } from "effect"
*
* assert.deepStrictEqual(BI.toNumber(BigInt(42)), Option.some(42))
* assert.deepStrictEqual(BI.toNumber(BigInt(Number.MAX_SAFE_INTEGER) + BigInt(1)), Option.none())
* assert.deepStrictEqual(BI.toNumber(BigInt(Number.MIN_SAFE_INTEGER) - BigInt(1)), Option.none())
+ * ```
*
* @category conversions
* @since 2.0.0
@@ -579,11 +629,13 @@ export const toNumber = (b: bigint): Option.Option => {
* @param s - The string to be converted to a `bigint`.
*
* @example
+ * ```ts
* import { BigInt as BI, Option } from "effect"
*
* assert.deepStrictEqual(BI.fromString("42"), Option.some(BigInt(42)))
* assert.deepStrictEqual(BI.fromString(" "), Option.none())
* assert.deepStrictEqual(BI.fromString("a"), Option.none())
+ * ```
*
* @category conversions
* @since 2.4.12
@@ -608,11 +660,13 @@ export const fromString = (s: string): Option.Option => {
* @param n - The number to be converted to a `bigint`.
*
* @example
+ * ```ts
* import { BigInt as BI, Option } from "effect"
*
* assert.deepStrictEqual(BI.fromNumber(42), Option.some(BigInt(42)))
* assert.deepStrictEqual(BI.fromNumber(Number.MAX_SAFE_INTEGER + 1), Option.none())
* assert.deepStrictEqual(BI.fromNumber(Number.MIN_SAFE_INTEGER - 1), Option.none())
+ * ```
*
* @category conversions
* @since 2.4.12
diff --git a/packages/effect/src/Boolean.ts b/packages/effect/src/Boolean.ts
index 5b26c8ef445..f15df71367c 100644
--- a/packages/effect/src/Boolean.ts
+++ b/packages/effect/src/Boolean.ts
@@ -17,10 +17,12 @@ import * as predicate from "./Predicate.js"
* @param input - The value to test.
*
* @example
+ * ```ts
* import { isBoolean } from "effect/Boolean"
*
* assert.deepStrictEqual(isBoolean(true), true)
* assert.deepStrictEqual(isBoolean("true"), false)
+ * ```
*
* @category guards
* @since 2.0.0
@@ -36,9 +38,11 @@ export const isBoolean: (input: unknown) => input is boolean = predicate.isBoole
* @param onTrue - a lazy evaluation function that will be executed when the `value` is `true`.
*
* @example
+ * ```ts
* import { Boolean } from "effect"
*
* assert.deepStrictEqual(Boolean.match(true, { onFalse: () => "It's false!", onTrue: () => "It's true!" }), "It's true!")
+ * ```
*
* @category pattern matching
* @since 2.0.0
@@ -73,10 +77,12 @@ export const Order: order.Order = order.boolean
* Negates the given boolean: `!self`
*
* @example
+ * ```ts
* import { not } from "effect/Boolean"
*
* assert.deepStrictEqual(not(true), false)
* assert.deepStrictEqual(not(false), true)
+ * ```
*
* @category combinators
* @since 2.0.0
@@ -87,12 +93,14 @@ export const not = (self: boolean): boolean => !self
* Combines two boolean using AND: `self && that`.
*
* @example
+ * ```ts
* import { and } from "effect/Boolean"
*
* assert.deepStrictEqual(and(true, true), true)
* assert.deepStrictEqual(and(true, false), false)
* assert.deepStrictEqual(and(false, true), false)
* assert.deepStrictEqual(and(false, false), false)
+ * ```
*
* @category combinators
* @since 2.0.0
@@ -106,12 +114,14 @@ export const and: {
* Combines two boolean using NAND: `!(self && that)`.
*
* @example
+ * ```ts
* import { nand } from "effect/Boolean"
*
* assert.deepStrictEqual(nand(true, true), false)
* assert.deepStrictEqual(nand(true, false), true)
* assert.deepStrictEqual(nand(false, true), true)
* assert.deepStrictEqual(nand(false, false), true)
+ * ```
*
* @category combinators
* @since 2.0.0
@@ -125,12 +135,14 @@ export const nand: {
* Combines two boolean using OR: `self || that`.
*
* @example
+ * ```ts
* import { or } from "effect/Boolean"
*
* assert.deepStrictEqual(or(true, true), true)
* assert.deepStrictEqual(or(true, false), true)
* assert.deepStrictEqual(or(false, true), true)
* assert.deepStrictEqual(or(false, false), false)
+ * ```
*
* @category combinators
* @since 2.0.0
@@ -144,12 +156,14 @@ export const or: {
* Combines two booleans using NOR: `!(self || that)`.
*
* @example
+ * ```ts
* import { nor } from "effect/Boolean"
*
* assert.deepStrictEqual(nor(true, true), false)
* assert.deepStrictEqual(nor(true, false), false)
* assert.deepStrictEqual(nor(false, true), false)
* assert.deepStrictEqual(nor(false, false), true)
+ * ```
*
* @category combinators
* @since 2.0.0
@@ -163,12 +177,14 @@ export const nor: {
* Combines two booleans using XOR: `(!self && that) || (self && !that)`.
*
* @example
+ * ```ts
* import { xor } from "effect/Boolean"
*
* assert.deepStrictEqual(xor(true, true), false)
* assert.deepStrictEqual(xor(true, false), true)
* assert.deepStrictEqual(xor(false, true), true)
* assert.deepStrictEqual(xor(false, false), false)
+ * ```
*
* @category combinators
* @since 2.0.0
@@ -182,12 +198,14 @@ export const xor: {
* Combines two booleans using EQV (aka XNOR): `!xor(self, that)`.
*
* @example
+ * ```ts
* import { eqv } from "effect/Boolean"
*
* assert.deepStrictEqual(eqv(true, true), true)
* assert.deepStrictEqual(eqv(true, false), false)
* assert.deepStrictEqual(eqv(false, true), false)
* assert.deepStrictEqual(eqv(false, false), true)
+ * ```
*
* @category combinators
* @since 2.0.0
@@ -201,12 +219,14 @@ export const eqv: {
* Combines two booleans using an implication: `(!self || that)`.
*
* @example
+ * ```ts
* import { implies } from "effect/Boolean"
*
* assert.deepStrictEqual(implies(true, true), true)
* assert.deepStrictEqual(implies(true, false), false)
* assert.deepStrictEqual(implies(false, true), true)
* assert.deepStrictEqual(implies(false, false), true)
+ * ```
*
* @category combinators
* @since 2.0.0
@@ -222,10 +242,12 @@ export const implies: {
* @param collection - An iterable collection of booleans.
*
* @example
+ * ```ts
* import { every } from "effect/Boolean"
*
* assert.deepStrictEqual(every([true, true, true]), true)
* assert.deepStrictEqual(every([true, false, true]), false)
+ * ```
*
* @since 2.0.0
*/
@@ -244,10 +266,12 @@ export const every = (collection: Iterable): boolean => {
* @param collection - An iterable collection of booleans.
*
* @example
+ * ```ts
* import { some } from "effect/Boolean"
*
* assert.deepStrictEqual(some([true, false, true]), true)
* assert.deepStrictEqual(some([false, false, false]), false)
+ * ```
*
* @since 2.0.0
*/
diff --git a/packages/effect/src/Brand.ts b/packages/effect/src/Brand.ts
index 48925de65d3..d3569a46916 100644
--- a/packages/effect/src/Brand.ts
+++ b/packages/effect/src/Brand.ts
@@ -196,6 +196,7 @@ export const errors: (...errors: Array) => Brand.BrandErrors
* @param onFailure - Takes the unbranded value that did not pass the `refinement` predicate and returns a `BrandErrors`.
*
* @example
+ * ```ts
* import { Brand } from "effect"
*
* type Int = number & Brand.Brand<"Int">
@@ -207,6 +208,7 @@ export const errors: (...errors: Array) => Brand.BrandErrors
*
* assert.strictEqual(Int(1), 1)
* assert.throws(() => Int(1.1))
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -247,6 +249,7 @@ export function refined>(
* If you also want to perform some validation, see {@link refined}.
*
* @example
+ * ```ts
* import { Brand } from "effect"
*
* type UserId = number & Brand.Brand<"UserId">
@@ -254,6 +257,7 @@ export function refined>(
* const UserId = Brand.nominal()
*
* assert.strictEqual(UserId(1), 1)
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -275,6 +279,7 @@ export const nominal = >(): Brand.Constructor<
* This API is useful when you want to validate that the input data passes multiple brand validators.
*
* @example
+ * ```ts
* import { Brand } from "effect"
*
* type Int = number & Brand.Brand<"Int">
@@ -292,6 +297,7 @@ export const nominal = >(): Brand.Constructor<
*
* assert.strictEqual(PositiveInt(1), 1)
* assert.throws(() => PositiveInt(1.1))
+ * ```
*
* @since 2.0.0
* @category combining
diff --git a/packages/effect/src/Chunk.ts b/packages/effect/src/Chunk.ts
index ab7ddffab32..60ac5f071e5 100644
--- a/packages/effect/src/Chunk.ts
+++ b/packages/effect/src/Chunk.ts
@@ -350,11 +350,13 @@ const reverseChunk = (self: Chunk): Chunk => {
* Importantly, if the input chunk is a `NonEmptyChunk`, the reversed chunk will also be a `NonEmptyChunk`.
*
* @example
+ * ```ts
* import { Chunk } from "effect"
*
* const numbers = Chunk.make(1, 2, 3)
* const reversedNumbers = Chunk.reverse(numbers)
* assert.deepStrictEqual(reversedNumbers, Chunk.make(3, 2, 1))
+ * ```
*
* @since 2.0.0
* @category elements
@@ -576,12 +578,14 @@ export const dropWhile: {
* If either chunk is non-empty, the result is also a non-empty chunk.
*
* @example
+ * ```ts
* import { Chunk } from "effect"
*
* assert.deepStrictEqual(
* Chunk.make(1, 2).pipe(Chunk.prependAll(Chunk.make("a", "b")), Chunk.toArray),
* ["a", "b", 1, 2]
* )
+ * ```
*
* @category concatenating
* @since 2.0.0
@@ -600,12 +604,14 @@ export const prependAll: {
* If either chunk is non-empty, the result is also a non-empty chunk.
*
* @example
+ * ```ts
* import { Chunk } from "effect"
*
* assert.deepStrictEqual(
* Chunk.make(1, 2).pipe(Chunk.appendAll(Chunk.make("a", "b")), Chunk.toArray),
* [1, 2, "a", "b"]
* )
+ * ```
*
* @category concatenating
* @since 2.0.0
@@ -903,12 +909,14 @@ export declare namespace Chunk {
* If the input chunk is non-empty, the resulting chunk will also be non-empty.
*
* @example
+ * ```ts
* import { Chunk } from "effect"
*
* assert.deepStrictEqual(
* Chunk.map(Chunk.make(1, 2), (n) => n + 1),
* Chunk.make(2, 3)
* )
+ * ```
*
* @since 2.0.0
* @category mapping
diff --git a/packages/effect/src/Config.ts b/packages/effect/src/Config.ts
index 04f82fcccd6..69bc2681808 100644
--- a/packages/effect/src/Config.ts
+++ b/packages/effect/src/Config.ts
@@ -172,9 +172,11 @@ export const integer: (name?: string) => Config = internal.integer
* Constructs a config for a literal value.
*
* @example
+ * ```ts
* import { Config } from "effect"
*
* const config = Config.literal("http", "https")("PROTOCOL")
+ * ```
*
* @since 2.0.0
* @category constructors
diff --git a/packages/effect/src/Context.ts b/packages/effect/src/Context.ts
index b91ef354607..fb53b708097 100644
--- a/packages/effect/src/Context.ts
+++ b/packages/effect/src/Context.ts
@@ -101,9 +101,11 @@ export declare namespace Tag {
* @param key - A key that will be used to compare tags.
*
* @example
+ * ```ts
* import { Context } from "effect"
*
* assert.strictEqual(Context.GenericTag("PORT").key === Context.GenericTag("PORT").key, true)
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -148,9 +150,11 @@ export const unsafeMake: (unsafeMap: Map) => Context input is Context = internal.i
* @param input - The value to be checked if it is a `Tag`.
*
* @example
+ * ```ts
* import { Context } from "effect"
*
* assert.strictEqual(Context.isTag(Context.GenericTag("Tag")), true)
+ * ```
*
* @since 2.0.0
* @category guards
@@ -176,9 +182,11 @@ export const isTag: (input: unknown) => input is Tag = internal.isTag
* Returns an empty `Context`.
*
* @example
+ * ```ts
* import { Context } from "effect"
*
* assert.strictEqual(Context.isContext(Context.empty()), true)
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -189,6 +197,7 @@ export const empty: () => Context = internal.empty
* Creates a new `Context` with a single service associated to the tag.
*
* @example
+ * ```ts
* import { Context } from "effect"
*
* const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -196,6 +205,7 @@ export const empty: () => Context = internal.empty
* const Services = Context.make(Port, { PORT: 8080 })
*
* assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -207,6 +217,7 @@ export const make: >(tag: T, service: Tag.Service) =>
* Adds a service to a given `Context`.
*
* @example
+ * ```ts
* import { Context, pipe } from "effect"
*
* const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -221,6 +232,7 @@ export const make: >(tag: T, service: Tag.Service) =>
*
* assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
* assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+ * ```
*
* @since 2.0.0
*/
@@ -243,6 +255,7 @@ export const add: {
* @param tag - The `Tag` of the service to retrieve.
*
* @example
+ * ```ts
* import { pipe, Context } from "effect"
*
* const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -254,6 +267,7 @@ export const add: {
* )
*
* assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+ * ```
*
* @since 2.0.0
* @category getters
@@ -285,6 +299,7 @@ export const getOrElse: {
* @param tag - The `Tag` of the service to retrieve.
*
* @example
+ * ```ts
* import { Context } from "effect"
*
* const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -294,6 +309,7 @@ export const getOrElse: {
*
* assert.deepStrictEqual(Context.unsafeGet(Services, Port), { PORT: 8080 })
* assert.throws(() => Context.unsafeGet(Services, Timeout))
+ * ```
*
* @since 2.0.0
* @category unsafe
@@ -311,6 +327,7 @@ export const unsafeGet: {
* @param tag - The `Tag` of the service to retrieve.
*
* @example
+ * ```ts
* import { Context, Option } from "effect"
*
* const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -320,6 +337,7 @@ export const unsafeGet: {
*
* assert.deepStrictEqual(Context.getOption(Services, Port), Option.some({ PORT: 8080 }))
* assert.deepStrictEqual(Context.getOption(Services, Timeout), Option.none())
+ * ```
*
* @since 2.0.0
* @category getters
@@ -336,6 +354,7 @@ export const getOption: {
* @param that - The second `Context` to merge.
*
* @example
+ * ```ts
* import { Context } from "effect"
*
* const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -348,6 +367,7 @@ export const getOption: {
*
* assert.deepStrictEqual(Context.get(Services, Port), { PORT: 8080 })
* assert.deepStrictEqual(Context.get(Services, Timeout), { TIMEOUT: 5000 })
+ * ```
*
* @since 2.0.0
*/
@@ -363,6 +383,7 @@ export const merge: {
* @param tags - The list of `Tag`s to be included in the new `Context`.
*
* @example
+ * ```ts
* import { pipe, Context, Option } from "effect"
*
* const Port = Context.GenericTag<{ PORT: number }>("Port")
@@ -377,6 +398,7 @@ export const merge: {
*
* assert.deepStrictEqual(Context.getOption(Services, Port), Option.some({ PORT: 8080 }))
* assert.deepStrictEqual(Context.getOption(Services, Timeout), Option.none())
+ * ```
*
* @since 2.0.0
*/
@@ -394,6 +416,7 @@ export const omit: >>(
/**
* @example
+ * ```ts
* import { Context, Layer } from "effect"
*
* class MyTag extends Context.Tag("MyTag")<
@@ -402,6 +425,7 @@ export const omit: >>(
* >() {
* static Live = Layer.succeed(this, { myNum: 108 })
* }
+ * ```
*
* @since 2.0.0
* @category constructors
diff --git a/packages/effect/src/Cron.ts b/packages/effect/src/Cron.ts
index 856d6c0b443..83d67dc64aa 100644
--- a/packages/effect/src/Cron.ts
+++ b/packages/effect/src/Cron.ts
@@ -170,6 +170,7 @@ export const isParseError = (u: unknown): u is ParseError => hasProperty(u, Pars
* @param cron - The cron expression to parse.
*
* @example
+ * ```ts
* import { Cron, Either } from "effect"
*
* // At 04:00 on every day-of-month from 8 through 14.
@@ -180,6 +181,7 @@ export const isParseError = (u: unknown): u is ParseError => hasProperty(u, Pars
* months: [],
* weekdays: []
* })))
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -207,11 +209,13 @@ export const parse = (cron: string): Either.Either => {
* @param date - The `Date` to check against.
*
* @example
+ * ```ts
* import { Cron, Either } from "effect"
*
* const cron = Either.getOrThrow(Cron.parse("0 4 8-14 * *"))
* assert.deepStrictEqual(Cron.match(cron, new Date("2021-01-08 04:00:00")), true)
* assert.deepStrictEqual(Cron.match(cron, new Date("2021-01-08 05:00:00")), false)
+ * ```
*
* @since 2.0.0
*/
@@ -256,11 +260,13 @@ export const match = (cron: Cron, date: Date): boolean => {
* Uses the current time as a starting point if no value is provided for `now`.
*
* @example
+ * ```ts
* import { Cron, Either } from "effect"
*
* const after = new Date("2021-01-01 00:00:00")
* const cron = Either.getOrThrow(Cron.parse("0 4 8-14 * *"))
* assert.deepStrictEqual(Cron.next(cron, after), new Date("2021-01-08 04:00:00"))
+ * ```
*
* @param cron - The `Cron` instance.
* @param now - The `Date` to start searching from.
diff --git a/packages/effect/src/Data.ts b/packages/effect/src/Data.ts
index 6b02cc2df75..1656e54ba89 100644
--- a/packages/effect/src/Data.ts
+++ b/packages/effect/src/Data.ts
@@ -27,6 +27,7 @@ export declare namespace Case {
/**
* @example
+ * ```ts
* import { Data, Equal } from "effect"
*
* const alice = Data.struct({ name: "Alice", age: 30 })
@@ -38,6 +39,7 @@ export declare namespace Case {
*
* assert.deepStrictEqual(Equal.equals(alice, { name: "Alice", age: 30 }), false)
* assert.deepStrictEqual(Equal.equals(alice, bob), false)
+ * ```
*
* @category constructors
* @since 2.0.0
@@ -53,6 +55,7 @@ export const unsafeStruct = >(as: A): { readonly [
/**
* @example
+ * ```ts
* import { Data, Equal } from "effect"
*
* const alice = Data.tuple("Alice", 30)
@@ -64,6 +67,7 @@ export const unsafeStruct = >(as: A): { readonly [
*
* assert.deepStrictEqual(Equal.equals(alice, ["Alice", 30]), false)
* assert.deepStrictEqual(Equal.equals(alice, bob), false)
+ * ```
*
* @category constructors
* @since 2.0.0
@@ -72,6 +76,7 @@ export const tuple = >(...as: As): Readonly =>
/**
* @example
+ * ```ts
* import { Data, Equal } from "effect"
*
* const alice = Data.struct({ name: "Alice", age: 30 })
@@ -89,6 +94,7 @@ export const tuple = >(...as: As): Readonly =>
* ),
* true
* )
+ * ```
*
* @category constructors
* @since 2.0.0
@@ -110,6 +116,7 @@ export {
* Provides a constructor for the specified `Case`.
*
* @example
+ * ```ts
* import { Data, Equal } from "effect"
*
* interface Person {
@@ -128,6 +135,7 @@ export {
* assert.deepStrictEqual(Equal.equals(mike1, mike2), true)
* assert.deepStrictEqual(Equal.equals(mike1, john), false)
*
+ * ```
* @since 2.0.0
* @category constructors
*/
@@ -138,6 +146,7 @@ export {
* Provides a tagged constructor for the specified `Case`.
*
* @example
+ * ```ts
* import { Data } from "effect"
*
* interface Person {
@@ -150,6 +159,7 @@ export {
* const mike = Person({ name: "Mike" })
*
* assert.deepEqual(mike, { _tag: "Person", name: "Mike" })
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -167,6 +177,7 @@ export const tagged = (
* Provides a constructor for a Case Class.
*
* @example
+ * ```ts
* import { Data, Equal } from "effect"
*
* class Person extends Data.Class<{ readonly name: string }> {}
@@ -179,6 +190,7 @@ export const tagged = (
* // Checking equality
* assert.deepStrictEqual(Equal.equals(mike1, mike2), true)
* assert.deepStrictEqual(Equal.equals(mike1, john), false)
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -192,6 +204,7 @@ export const Class: new = {}>(
* Provides a Tagged constructor for a Case Class.
*
* @example
+ * ```ts
* import { Data, Equal } from "effect"
*
* class Person extends Data.TaggedClass("Person")<{ readonly name: string }> {}
@@ -206,6 +219,7 @@ export const Class: new = {}>(
* assert.deepStrictEqual(Equal.equals(mike1, john), false)
*
* assert.deepStrictEqual(mike1._tag, "Person")
+ * ```
*
* @since 2.0.0
* @category constructors
@@ -403,6 +417,7 @@ export declare namespace TaggedEnum {
* the constructor.
*
* @example
+ * ```ts
* import { Data } from "effect"
*
* const { BadRequest, NotFound } = Data.taggedEnum<
@@ -411,6 +426,7 @@ export declare namespace TaggedEnum {
* >()
*
* const notFound = NotFound({ status: 404, message: "Not Found" })
+ * ```
*
* @example
* import { Data } from "effect"
diff --git a/packages/effect/src/DateTime.ts b/packages/effect/src/DateTime.ts
index 4d847b2b7d8..89e8556d466 100644
--- a/packages/effect/src/DateTime.ts
+++ b/packages/effect/src/DateTime.ts
@@ -436,6 +436,7 @@ export const unsafeFromDate = (date: Date): Utc => {
* @since 3.6.0
* @category constructors
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // from Date
@@ -446,6 +447,7 @@ export const unsafeFromDate = (date: Date): Utc => {
*
* // from string
* DateTime.unsafeMake("2024-01-01")
+ * ```
*/
export const unsafeMake = (input: A): DateTime.PreserveZone => {
if (isDateTime(input)) {
@@ -470,9 +472,11 @@ export const unsafeMake = (input: A): DateTime.Preserv
* @since 3.6.0
* @category constructors
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* DateTime.unsafeMakeZoned(new Date(), { timeZone: "Europe/London" })
+ * ```
*/
export const unsafeMakeZoned = (input: DateTime.Input, options?: {
readonly timeZone?: number | string | TimeZone | undefined
@@ -513,9 +517,11 @@ export const unsafeMakeZoned = (input: DateTime.Input, options?: {
* @since 3.6.0
* @category constructors
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* DateTime.makeZoned(new Date(), { timeZone: "Europe/London" })
+ * ```
*/
export const makeZoned: (
input: DateTime.Input,
@@ -539,6 +545,7 @@ export const makeZoned: (
* @since 3.6.0
* @category constructors
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // from Date
@@ -549,6 +556,7 @@ export const makeZoned: (
*
* // from string
* DateTime.make("2024-01-01")
+ * ```
*/
export const make: (input: A) => Option.Option> = Option
.liftThrowable(unsafeMake)
@@ -579,11 +587,13 @@ export const makeZonedFromString = (input: string): Option.Option => {
* @since 3.6.0
* @category constructors
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
* const now = yield* DateTime.now
* })
+ * ```
*/
export const now: Effect.Effect = Effect.map(Clock.currentTimeMillis, makeUtc)
@@ -605,6 +615,7 @@ export const unsafeNow: LazyArg = () => makeUtc(Date.now())
* @since 3.6.0
* @category time zones
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
@@ -614,6 +625,7 @@ export const unsafeNow: LazyArg = () => makeUtc(Date.now())
* // set the time zone
* const zoned: DateTime.Zoned = DateTime.setZone(now, zone)
* })
+ * ```
*/
export const setZone: {
(zone: TimeZone, options?: {
@@ -637,6 +649,7 @@ export const setZone: {
* @since 3.6.0
* @category time zones
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
@@ -645,6 +658,7 @@ export const setZone: {
* // set the offset time zone in milliseconds
* const zoned: DateTime.Zoned = DateTime.setZoneOffset(now, 3 * 60 * 60 * 1000)
* })
+ * ```
*/
export const setZoneOffset: {
(offset: number, options?: {
@@ -773,6 +787,7 @@ export const zoneFromString = (zone: string): Option.Option => {
* @since 3.6.0
* @category time zones
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* // Outputs "+03:00"
@@ -780,6 +795,7 @@ export const zoneFromString = (zone: string): Option.Option => {
*
* // Outputs "Europe/London"
* DateTime.zoneToString(DateTime.zoneUnsafeMakeNamed("Europe/London"))
+ * ```
*/
export const zoneToString = (self: TimeZone): string => {
if (self._tag === "Offset") {
@@ -795,6 +811,7 @@ export const zoneToString = (self: TimeZone): string => {
* @since 3.6.0
* @category time zones
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
@@ -802,6 +819,7 @@ export const zoneToString = (self: TimeZone): string => {
* // set the time zone, returns an Option
* DateTime.setZoneNamed(now, "Europe/London")
* })
+ * ```
*/
export const setZoneNamed: {
(zoneId: string, options?: {
@@ -824,6 +842,7 @@ export const setZoneNamed: {
* @since 3.6.0
* @category time zones
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
@@ -831,6 +850,7 @@ export const setZoneNamed: {
* // set the time zone
* DateTime.unsafeSetZoneNamed(now, "Europe/London")
* })
+ * ```
*/
export const unsafeSetZoneNamed: {
(zoneId: string, options?: {
@@ -856,6 +876,7 @@ export const unsafeSetZoneNamed: {
* @since 3.6.0
* @category comparisons
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
@@ -865,6 +886,7 @@ export const unsafeSetZoneNamed: {
* // returns 60000
* DateTime.distance(now, other)
* })
+ * ```
*/
export const distance: {
(other: DateTime): (self: DateTime) => number
@@ -883,6 +905,7 @@ export const distance: {
* @since 3.6.0
* @category comparisons
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
@@ -895,6 +918,7 @@ export const distance: {
* // returns Either.left(Duration.minutes(1))
* DateTime.distanceDurationEither(other, now)
* })
+ * ```
*/
export const distanceDurationEither: {
(other: DateTime): (self: DateTime) => Either.Either
@@ -912,6 +936,7 @@ export const distanceDurationEither: {
* @since 3.6.0
* @category comparisons
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
@@ -921,6 +946,7 @@ export const distanceDurationEither: {
* // returns Duration.minutes(1)
* DateTime.distanceDuration(now, other)
* })
+ * ```
*/
export const distanceDuration: {
(other: DateTime): (self: DateTime) => Duration.Duration
@@ -1103,6 +1129,7 @@ export const toEpochMillis = (self: DateTime): number => self.epochMillis
* @since 3.6.0
* @category conversions
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // returns "2024-01-01T00:00:00Z"
@@ -1113,6 +1140,7 @@ export const toEpochMillis = (self: DateTime): number => self.epochMillis
* DateTime.removeTime,
* DateTime.formatIso
* )
+ * ```
*/
export const removeTime = (self: DateTime): Utc =>
withDate(self, (date) => {
@@ -1177,11 +1205,13 @@ export const toPartsUtc = (self: DateTime): DateTime.PartsWithWeekday => {
* @since 3.6.0
* @category parts
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* const now = DateTime.unsafeMake({ year: 2024 })
* const year = DateTime.getPartUtc(now, "year")
* assert.strictEqual(year, 2024)
+ * ```
*/
export const getPartUtc: {
(part: keyof DateTime.PartsWithWeekday): (self: DateTime) => number
@@ -1196,11 +1226,13 @@ export const getPartUtc: {
* @since 3.6.0
* @category parts
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* const now = DateTime.unsafeMakeZoned({ year: 2024 }, { timeZone: "Europe/London" })
* const year = DateTime.getPart(now, "year")
* assert.strictEqual(year, 2024)
+ * ```
*/
export const getPart: {
(part: keyof DateTime.PartsWithWeekday): (self: DateTime) => number
@@ -1287,6 +1319,7 @@ export class CurrentTimeZone extends Context.Tag("effect/DateTime/CurrentTimeZon
* @since 3.6.0
* @category current time zone
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
@@ -1295,6 +1328,7 @@ export class CurrentTimeZone extends Context.Tag("effect/DateTime/CurrentTimeZon
* // set the time zone to "Europe/London"
* const zoned = yield* DateTime.setZoneCurrent(now)
* }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
+ * ```
*/
export const setZoneCurrent = (self: DateTime): Effect.Effect =>
Effect.map(CurrentTimeZone, (zone) => setZone(self, zone))
@@ -1305,6 +1339,7 @@ export const setZoneCurrent = (self: DateTime): Effect.Effect(effect: Effect.Effect) => Effect.Effect>
@@ -1329,12 +1365,14 @@ export const withCurrentZone: {
* @since 3.6.0
* @category current time zone
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
* // will use the system's local time zone
* const now = yield* DateTime.nowInCurrentZone
* }).pipe(DateTime.withCurrentZoneLocal)
+ * ```
*/
export const withCurrentZoneLocal = (
effect: Effect.Effect
@@ -1347,12 +1385,14 @@ export const withCurrentZoneLocal = (
* @since 3.6.0
* @category current time zone
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
* // will use the system's local time zone
* const now = yield* DateTime.nowInCurrentZone
* }).pipe(DateTime.withCurrentZoneOffset(3 * 60 * 60 * 1000))
+ * ```
*/
export const withCurrentZoneOffset: {
(offset: number): (
@@ -1374,12 +1414,14 @@ export const withCurrentZoneOffset: {
* @since 3.6.0
* @category current time zone
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
* // will use the "Europe/London" time zone
* const now = yield* DateTime.nowInCurrentZone
* }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
+ * ```
*/
export const withCurrentZoneNamed: {
(zone: string): (
@@ -1404,12 +1446,14 @@ export const withCurrentZoneNamed: {
* @since 3.6.0
* @category current time zone
* @example
+ * ```ts
* import { DateTime, Effect } from "effect"
*
* Effect.gen(function* () {
* // will use the "Europe/London" time zone
* const now = yield* DateTime.nowInCurrentZone
* }).pipe(DateTime.withCurrentZoneNamed("Europe/London"))
+ * ```
*/
export const nowInCurrentZone: Effect.Effect = Effect.flatMap(
now,
@@ -1532,12 +1576,14 @@ export const mutateUtc: {
* @since 3.6.0
* @category mapping
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // add 10 milliseconds
* DateTime.unsafeMake(0).pipe(
* DateTime.mapEpochMillis((millis) => millis + 10)
* )
+ * ```
*/
export const mapEpochMillis: {
(f: (millis: number) => number): (self: A) => DateTime.PreserveZone
@@ -1554,12 +1600,14 @@ export const mapEpochMillis: {
* @since 3.6.0
* @category mapping
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // get the time zone adjusted date in milliseconds
* DateTime.unsafeMakeZoned(0, { timeZone: "Europe/London" }).pipe(
* DateTime.withDate((date) => date.getTime())
* )
+ * ```
*/
export const withDate: {
(f: (date: Date) => A): (self: DateTime) => A
@@ -1573,12 +1621,14 @@ export const withDate: {
* @since 3.6.0
* @category mapping
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // get the date in milliseconds
* DateTime.unsafeMake(0).pipe(
* DateTime.withDateUtc((date) => date.getTime())
* )
+ * ```
*/
export const withDateUtc: {
(f: (date: Date) => A): (self: DateTime) => A
@@ -1613,12 +1663,14 @@ export const match: {
* @since 3.6.0
* @category math
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // add 5 minutes
* DateTime.unsafeMake(0).pipe(
* DateTime.addDuration("5 minutes")
* )
+ * ```
*/
export const addDuration: {
(duration: Duration.DurationInput): (self: A) => DateTime.PreserveZone
@@ -1635,12 +1687,14 @@ export const addDuration: {
* @since 3.6.0
* @category math
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // subtract 5 minutes
* DateTime.unsafeMake(0).pipe(
* DateTime.subtractDuration("5 minutes")
* )
+ * ```
*/
export const subtractDuration: {
(duration: Duration.DurationInput): (self: A) => DateTime.PreserveZone
@@ -1664,12 +1718,14 @@ const addMillis = (date: Date, amount: number): void => {
* @since 3.6.0
* @category math
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // add 5 minutes
* DateTime.unsafeMake(0).pipe(
* DateTime.add({ minutes: 5 })
* )
+ * ```
*/
export const add: {
(parts: Partial): (self: A) => DateTime.PreserveZone
@@ -1721,12 +1777,14 @@ export const add: {
* @since 3.6.0
* @category math
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // subtract 5 minutes
* DateTime.unsafeMake(0).pipe(
* DateTime.subtract({ minutes: 5 })
* )
+ * ```
*/
export const subtract: {
(parts: Partial): (self: A) => DateTime.PreserveZone
@@ -1789,6 +1847,7 @@ function startOfDate(date: Date, part: DateTime.UnitSingular, options?: {
* @since 3.6.0
* @category math
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // returns "2024-01-01T00:00:00Z"
@@ -1796,6 +1855,7 @@ function startOfDate(date: Date, part: DateTime.UnitSingular, options?: {
* DateTime.startOf("day"),
* DateTime.formatIso
* )
+ * ```
*/
export const startOf: {
(part: DateTime.UnitSingular, options?: {
@@ -1858,6 +1918,7 @@ function endOfDate(date: Date, part: DateTime.UnitSingular, options?: {
* @since 3.6.0
* @category math
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // returns "2024-01-01T23:59:59.999Z"
@@ -1865,6 +1926,7 @@ function endOfDate(date: Date, part: DateTime.UnitSingular, options?: {
* DateTime.endOf("day"),
* DateTime.formatIso
* )
+ * ```
*/
export const endOf: {
(part: DateTime.UnitSingular, options?: {
@@ -1886,6 +1948,7 @@ export const endOf: {
* @since 3.6.0
* @category math
* @example
+ * ```ts
* import { DateTime } from "effect"
*
* // returns "2024-01-02T00:00:00Z"
@@ -1893,6 +1956,7 @@ export const endOf: {
* DateTime.nearest("day"),
* DateTime.formatIso
* )
+ * ```
*/
export const nearest: {
(part: DateTime.UnitSingular, options?: {
diff --git a/packages/effect/src/Duration.ts b/packages/effect/src/Duration.ts
index 1af113a5b50..b976453f798 100644
--- a/packages/effect/src/Duration.ts
+++ b/packages/effect/src/Duration.ts
@@ -796,10 +796,12 @@ export const parts = (self: DurationInput): {
* @since 2.0.0
* @category conversions
* @example
+ * ```ts
* import { Duration } from "effect"
*
* Duration.format(Duration.millis(1000)) // "1s"
* Duration.format(Duration.millis(1001)) // "1s 1ms"
+ * ```
*/
export const format = (self: DurationInput): string => {
const duration = decode(self)
diff --git a/packages/effect/src/Effect.ts b/packages/effect/src/Effect.ts
index d2f25774b54..afbc5329082 100644
--- a/packages/effect/src/Effect.ts
+++ b/packages/effect/src/Effect.ts
@@ -256,6 +256,7 @@ export const isEffect: (u: unknown) => u is Effect =
* be recomputed upon next evaluation.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* let i = 1
@@ -283,6 +284,7 @@ export const isEffect: (u: unknown) => u is Effect =
* // result 1
* // expensive task...
* // result 2
+ * ```
*
* @since 2.0.0
* @category Caching
@@ -298,6 +300,7 @@ export const cachedWithTTL: {
* invalidating the cached value before it naturally expires.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* let i = 1
@@ -328,6 +331,7 @@ export const cachedWithTTL: {
* // result 1
* // expensive task...
* // result 2
+ * ```
*
* @since 2.0.0
* @category Caching
@@ -348,6 +352,7 @@ export const cachedInvalidateWithTTL: {
* the logic.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* let i = 1
@@ -381,6 +386,7 @@ export const cachedInvalidateWithTTL: {
* // expensive task...
* // result 3
* // result 3
+ * ```
*
* @since 2.0.0
* @category Caching
@@ -393,6 +399,7 @@ export const cached: (self: Effect) => Effect>
* recompute them.
*
* @example
+ * ```ts
* import { Effect, Random } from "effect"
*
* const program = Effect.gen(function* () {
@@ -415,6 +422,7 @@ export const cached: (self: Effect) => Effect>
* // memoized version:
* // 5
* // 5
+ * ```
*
* @since 2.0.0
* @category Caching
@@ -429,6 +437,7 @@ export const cachedFunction: (
* called.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* const program = Effect.gen(function* () {
@@ -444,6 +453,7 @@ export const cachedFunction: (
* // task1
* // task1
* // task2
+ * ```
*
* @since 2.0.0
* @category Caching
@@ -500,6 +510,7 @@ export const once: (self: Effect) => Effect
* @see {@link forEach} for iterating over elements and applying an effect.
*
* @example
+ * ```ts
* // Title: Combining Effects in Tuples
* import { Effect, Console } from "effect"
*
@@ -517,6 +528,7 @@ export const once: (self: Effect) => Effect
* // 42
* // Hello
* // [ 42, 'Hello' ]
+ * ```
*
* @example
* // Title: Combining Effects in Iterables
@@ -675,6 +687,7 @@ export const all: <
* your data and then apply operations to it.
*
* @example
+ * ```ts
* import { Effect, pipe } from "effect"
*
* const task1 = Effect.succeed(1).pipe(
@@ -698,6 +711,7 @@ export const all: <
* // timestamp=... level=INFO fiber=#3 message="task2 done"
* // timestamp=... level=INFO fiber=#2 message="task1 done"
* // [ 1, 'hello' ]
+ * ```
*
* @since 2.0.0
* @category Collecting
@@ -942,6 +956,7 @@ export const filter: {
* @see {@link filter} for concurrent filtering without mapping.
*
* @example
+ * ```ts
* import { Console, Effect, Option } from "effect"
*
* const task = (n: number) =>
@@ -962,6 +977,7 @@ export const filter: {
* // task3 done
* // task4 done
* // [ 2, 4 ]
+ * ```
*
* @since 2.0.0
* @category Filtering
@@ -1016,6 +1032,7 @@ export const findFirst: {
* @see {@link all} for combining multiple effects into one.
*
* @example
+ * ```ts
* // Title: Applying Effects to Iterable Elements
* import { Effect, Console } from "effect"
*
@@ -1031,6 +1048,7 @@ export const findFirst: {
* // Currently at index 3
* // Currently at index 4
* // [ 2, 4, 6, 8, 10 ]
+ * ```
*
* @example
* // Title: Using discard to Ignore Results
@@ -1158,6 +1176,7 @@ export const mergeAll: {
* @see {@link validateFirst} for a function that stops at the first success.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* // ┌─── Effect<[string[], number[]], never, never>
@@ -1173,6 +1192,7 @@ export const mergeAll: {
* Effect.runPromise(program).then(console.log, console.error)
* // Output:
* // [ [ '1 is not even', '3 is not even' ], [ 0, 2, 4 ] ]
+ * ```
*
* @since 2.0.0
* @category Error Accumulation
@@ -1382,6 +1402,7 @@ export const takeWhile: {
* @see {@link partition} when you need to separate successes and failures instead of losing successes with errors.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* // ┌─── Effect
@@ -1408,6 +1429,7 @@ export const takeWhile: {
* // failure: [ '4 is not less that 4', '5 is not less that 4' ]
* // }
* // }
+ * ```
*
* @since 2.0.0
* @category Error Accumulation
@@ -1469,6 +1491,7 @@ export const validateAll: {
* @see {@link firstSuccessOf} for a similar function that processes multiple effects and returns the first successful one or the last error.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* // ┌─── Effect
@@ -1485,6 +1508,7 @@ export const validateAll: {
* // Output:
* // item 4
* // 4
+ * ```
*
* @since 2.0.0
* @category Error Accumulation
@@ -1538,6 +1562,7 @@ export const validateFirst: {
* behavior of the returned effect.
*
* @example
+ * ```ts
* // Title: Wrapping a Callback API
* import { Effect } from "effect"
* import * as NodeFS from "node:fs"
@@ -1558,6 +1583,7 @@ export const validateFirst: {
* // ┌─── Effect
* // ▼
* const program = readFile("example.txt")
+ * ```
*
* @example
* // Title: Handling Interruption with Cleanup
@@ -1655,12 +1681,14 @@ export const asyncEffect: (
* the "this" of the effect.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const throwingFunction = () => { throw new Error() }
* const blowUp = Effect.custom(throwingFunction, function() {
* return Effect.succeed(this.effect_instruction_i0())
* })
+ * ```
*
* @since 2.0.0
* @category Creating Effects
@@ -1703,6 +1731,7 @@ export const withFiberRuntime: (
* @see {@link succeed} to create an effect that represents a successful value.
*
* @example
+ * ```ts
* // Title: Creating a Failed Effect
* import { Effect } from "effect"
*
@@ -1711,6 +1740,7 @@ export const withFiberRuntime: (
* const failure = Effect.fail(
* new Error("Operation failed due to network error")
* )
+ * ```
*
* @since 2.0.0
* @category Creating Effects
@@ -1756,6 +1786,7 @@ export const failCauseSync: (evaluate: LazyArg>) => Effect(evaluate: LazyArg>) => Effect Effect = core.die
* lazily.
*
* @example
+ * ```ts
* // Title: Terminating on Division by Zero with a Specified Message
* import { Effect } from "effect"
*
@@ -1817,6 +1850,7 @@ export const die: (defect: unknown) => Effect = core.die
* // Output:
* // (FiberFailure) RuntimeException: Cannot divide by zero
* // ...stack trace...
+ * ```
*
* @since 2.0.0
* @category Creating Effects
@@ -1852,6 +1886,7 @@ export const dieSync: (evaluate: LazyArg) => Effect = core.dieSy
* effects and return the final result at the end.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const addServiceCharge = (amount: number) => amount + 1
@@ -1878,6 +1913,7 @@ export const dieSync: (evaluate: LazyArg) => Effect = core.dieSy
* const finalAmount = addServiceCharge(discountedAmount)
* return `Final amount to charge: ${finalAmount}`
* })
+ * ```
*
* @since 2.0.0
* @category Creating Effects
@@ -2211,6 +2247,7 @@ export const none: (
* @see {@link tryPromise} for a version that can handle failures.
*
* @example
+ * ```ts
* // Title: Delayed Message
* import { Effect } from "effect"
*
@@ -2227,6 +2264,7 @@ export const none: (
* // ┌─── Effect
* // ▼
* const program = delay("Async operation completed successfully!")
+ * ```
*
* @since 2.0.0
* @category Creating Effects
@@ -2246,6 +2284,7 @@ export const promise: (
* @see {@link fail} to create an effect that represents a failure.
*
* @example
+ * ```ts
* // Title: Creating a Successful Effect
* import { Effect } from "effect"
*
@@ -2254,6 +2293,7 @@ export const promise: (
* // ┌─── Effect
* // ▼
* const success = Effect.succeed(42)
+ * ```
*
* @since 2.0.0
* @category Creating Effects
@@ -2291,6 +2331,7 @@ export const succeedSome: (value: A) => Effect> = effect.suc
* - **Unifying Return Types**: Can help TypeScript unify return types in situations where multiple branches of logic return different effects, simplifying type inference.
*
* @example
+ * ```ts
* // Title: Lazy Evaluation with Side Effects
* import { Effect } from "effect"
*
@@ -2305,6 +2346,7 @@ export const succeedSome: (value: A) => Effect> = effect.suc
*
* console.log(Effect.runSync(good)) // Output: 1
* console.log(Effect.runSync(good)) // Output: 2
+ * ```
*
* @example
* // Title: Recursive Fibonacci
@@ -2378,6 +2420,7 @@ export const suspend: (effect: LazyArg>) => Effect(effect: LazyArg>) => Effect
* // ▼
* const program = log("Hello, World!")
+ * ```
*
* @since 2.0.0
* @category Creating Effects
@@ -2450,6 +2494,7 @@ export {
* @see {@link catchAllCause} for a version that can recover from both recoverable and unrecoverable errors.
*
* @example
+ * ```ts
* // Title: Providing Recovery Logic for Recoverable Errors
* import { Effect, Random } from "effect"
*
@@ -2482,6 +2527,7 @@ export {
* Effect.succeed(`Recovering from ${error._tag}`)
* )
* )
+ * ```
*
* @since 2.0.0
* @category Error handling
@@ -2509,6 +2555,7 @@ export const catchAll: {
* dynamically loaded plugins, controlled recovery might be needed.
*
* @example
+ * ```ts
* // Title: Recovering from All Errors
* import { Cause, Effect } from "effect"
*
@@ -2526,6 +2573,7 @@ export const catchAll: {
*
* Effect.runPromise(recovered).then(console.log)
* // Output: "Recovered from a regular error"
+ * ```
*
* @since 2.0.0
* @category Error handling
@@ -2564,6 +2612,7 @@ export const catchAllCause: {
* dynamically loaded plugins, controlled recovery might be needed.
*
* @example
+ * ```ts
* // Title: Handling All Defects
* import { Effect, Cause, Console } from "effect"
*
@@ -2588,6 +2637,7 @@ export const catchAllCause: {
* // _tag: "Success",
* // value: undefined
* // }
+ * ```
*
* @since 2.0.0
* @category Error handling
@@ -2614,6 +2664,7 @@ export const catchAllDefect: {
* error type unless a user-defined type guard is used to narrow the type.
*
* @example
+ * ```ts
* // Title: Catching Specific Errors with a Predicate
* import { Effect, Random } from "effect"
*
@@ -2648,6 +2699,7 @@ export const catchAllDefect: {
* () => Effect.succeed("Recovering from HttpError")
* )
* )
+ * ```
*
* @since 2.0.0
* @category Error handling
@@ -2688,6 +2740,7 @@ export const catchIf: {
* @see {@link catchIf} for a version that allows you to recover from errors based on a predicate.
*
* @example
+ * ```ts
* // Title: Handling Specific Errors with Effect.catchSome
* import { Effect, Random, Option } from "effect"
*
@@ -2725,6 +2778,7 @@ export const catchIf: {
* }
* })
* )
+ * ```
*
* @since 2.0.0
* @category Error handling
@@ -2782,6 +2836,7 @@ export const catchSomeCause: {
* - If the defect does not match, the function returns `Option.none`, allowing the defect to propagate.
*
* @example
+ * ```ts
* // Title: Handling Specific Defects
* import { Effect, Cause, Option, Console } from "effect"
*
@@ -2812,6 +2867,7 @@ export const catchSomeCause: {
* // defect: { _tag: 'RuntimeException' }
* // }
* // }
+ * ```
*
* @since 2.0.0
* @category Error handling
@@ -2844,6 +2900,7 @@ export const catchSomeDefect: {
* types at once.
*
* @example
+ * ```ts
* // Title: Handling Errors by Tag
* import { Effect, Random } from "effect"
*
@@ -2877,6 +2934,7 @@ export const catchSomeDefect: {
* Effect.succeed("Recovering from HttpError")
* )
* )
+ * ```
*
* @since 2.0.0
* @category Error handling
@@ -2908,6 +2966,7 @@ export const catchTag: {
* field is used to identify and match errors.
*
* @example
+ * ```ts
* // Title: Handling Multiple Tagged Error Types at Once
* import { Effect, Random } from "effect"
*
@@ -2943,6 +3002,7 @@ export const catchTag: {
* Effect.succeed(`Recovering from ValidationError`)
* })
* )
+ * ```
*
* @since 2.0.0
* @category Error handling
@@ -3009,6 +3069,7 @@ export const catchTags: {
* interruptions, etc.).
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* // ┌─── Effect
@@ -3021,6 +3082,7 @@ export const catchTags: {
* const cause = yield* Effect.cause(program)
* yield* Console.log(cause)
* })
+ * ```
*
* @since 2.0.0
* @category Error handling
@@ -3044,6 +3106,7 @@ export const eventually: (self: Effect) => Effect
* side effects of the effect and do not need to handle or process its outcome.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* // ┌─── Effect
@@ -3053,6 +3116,7 @@ export const eventually: (self: Effect) => Effect
* // ┌─── Effect
* // ▼
* const program = Effect.ignore(task)
+ * ```
*
* @since 2.0.0
* @category Error handling
@@ -3080,6 +3144,7 @@ export const ignoreLogged: (self: Effect) => Effect(self: Effect) => Effect(self: Effect) => Effect
@@ -3154,6 +3221,7 @@ export const parallelErrors: (self: Effect) => Effect
* // ▼
* const program = getTodo(1)
+ * ```
*
* @example
* // Title: Custom Error Handling
@@ -3559,6 +3635,7 @@ export const checkInterruptible: (f: (isInterruptible: boolean) => Effe
* @see {@link Effect.uninterruptible} for creating an uninterruptible effect.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const longRunningTask = Effect.gen(function* () {
@@ -3588,6 +3665,7 @@ export const checkInterruptible: (f: (isInterruptible: boolean) => Effe
* // }
* // }
* // Heavy processing done.
+ * ```
*
* @since 2.0.0
* @category Interruption
@@ -3653,6 +3731,7 @@ export const uninterruptibleMask: (
* or failing with specified error if the predicate fails
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const isPositive = (n: number): boolean => n > 0
@@ -3662,6 +3741,7 @@ export const uninterruptibleMask: (
*
* // fails with `"0 is not positive"`
* Effect.liftPredicate(0, isPositive, n => `${n} is not positive`)
+ * ```
*
* @category Condition Checking
* @since 3.4.0
@@ -3683,6 +3763,7 @@ export const liftPredicate: {
* replace it with a new constant value.
*
* @example
+ * ```ts
* // Title: Replacing a Value
* import { pipe, Effect } from "effect"
*
@@ -3691,6 +3772,7 @@ export const liftPredicate: {
*
* Effect.runPromise(program).then(console.log)
* // Output: "new value"
+ * ```
*
* @since 2.0.0
* @category Mapping
@@ -3741,6 +3823,7 @@ export const asVoid: (self: Effect) => Effect = co
* treat an error as a valid result.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* // ┌─── Effect
@@ -3750,6 +3833,7 @@ export const asVoid: (self: Effect) => Effect = co
* // ┌─── Effect
* // ▼
* const flipped = Effect.flip(program)
+ * ```
*
* @since 2.0.0
* @category Mapping
@@ -3800,6 +3884,7 @@ export const flipWith: {
* @see {@link flatMap} or {@link andThen} for a version that can return a new effect.
*
* @example
+ * ```ts
* // Title: Adding a Service Charge
* import { pipe, Effect } from "effect"
*
@@ -3814,6 +3899,7 @@ export const flipWith: {
*
* Effect.runPromise(finalAmount).then(console.log)
* // Output: 101
+ * ```
* @since 2.0.0
* @category Mapping
*/
@@ -3842,6 +3928,7 @@ export const map: {
* input collection type.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* // Define an initial state and a transformation function
@@ -3860,6 +3947,7 @@ export const map: {
* // Output:
* // 6
* // [ 'A', 'BB', 'CCC' ]
+ * ```
*
* @since 2.0.0
* @category Mapping
@@ -3889,6 +3977,7 @@ export const mapAccum: {
* @see {@link mapError} for a version that operates on the error channel.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* // ┌─── Effect
@@ -3901,6 +3990,7 @@ export const mapAccum: {
* onFailure: (message) => new Error(message),
* onSuccess: (n) => n > 0
* })
+ * ```
*
* @since 2.0.0
* @category Mapping
@@ -3929,6 +4019,7 @@ export const mapBoth: {
* @see {@link orElseFail} if you want to replace the error with a new one.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* // ┌─── Effect
@@ -3941,6 +4032,7 @@ export const mapBoth: {
* simulatedTask,
* (message) => new Error(message)
* )
+ * ```
*
* @since 2.0.0
* @category Mapping
@@ -3976,6 +4068,7 @@ export const mapErrorCause: {
* errors as part of the outcome.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* // ┌─── Effect
@@ -3985,6 +4078,7 @@ export const mapErrorCause: {
* // ┌─── Effect
* // ▼
* const recovered = Effect.merge(program)
+ * ```
*
* @since 2.0.0
* @category Mapping
@@ -4659,6 +4753,7 @@ export const timedWith: {
* @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const task = Effect.gen(function* () {
@@ -4684,6 +4779,7 @@ export const timedWith: {
* // failure: { _tag: 'TimeoutException' }
* // }
* // }
+ * ```
*
* @since 2.0.0
* @category delays & timeouts
@@ -4713,6 +4809,7 @@ export const timeout: {
* @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const task = Effect.gen(function* () {
@@ -4736,6 +4833,7 @@ export const timeout: {
* // { _id: 'Option', _tag: 'Some', value: 'Result' },
* // { _id: 'Option', _tag: 'None' }
* // ]
+ * ```
*
* @since 3.1.0
* @category delays & timeouts
@@ -4764,6 +4862,7 @@ export const timeoutOption: {
* @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const task = Effect.gen(function* () {
@@ -4796,6 +4895,7 @@ export const timeoutOption: {
* // failure: MyTimeoutError { _tag: 'MyTimeoutError' }
* // }
* // }
+ * ```
*
* @since 2.0.0
* @category delays & timeouts
@@ -4828,6 +4928,7 @@ export const timeoutFail: {
* @see {@link timeoutTo} for a version that allows specifying both success and timeout handlers.
*
* @example
+ * ```ts
* import { Effect, Cause } from "effect"
*
* const task = Effect.gen(function* () {
@@ -4852,6 +4953,7 @@ export const timeoutFail: {
* // _tag: 'Failure',
* // cause: { _id: 'Cause', _tag: 'Die', defect: 'Timed out!' }
* // }
+ * ```
*
* @since 2.0.0
* @category delays & timeouts
@@ -4888,6 +4990,7 @@ export const timeoutFailCause: {
* @see {@link timeoutFailCause} for a version that raises a custom defect.
*
* @example
+ * ```ts
* import { Effect, Either } from "effect"
*
* const task = Effect.gen(function* () {
@@ -4915,6 +5018,7 @@ export const timeoutFailCause: {
* // _tag: "Left",
* // left: "Timed out!"
* // }
+ * ```
*
* @since 2.0.0
* @category delays & timeouts
@@ -5015,6 +5119,7 @@ export const mapInputContext: {
* @see {@link provideService} for providing a service to an effect.
*
* @example
+ * ```ts
* import { Context, Effect, Layer } from "effect"
*
* class Database extends Context.Tag("Database")<
@@ -5046,6 +5151,7 @@ export const mapInputContext: {
* // Output:
* // timestamp=... level=INFO fiber=#0 message="Executing query: SELECT * FROM users"
* // []
+ * ```
*
* @since 2.0.0
* @category Context
@@ -5103,6 +5209,7 @@ export const provide: {
* @see {@link provide} for providing multiple layers to an effect.
*
* @example
+ * ```ts
* import { Effect, Context } from "effect"
*
* // Declaring a tag for a service that generates random numbers
@@ -5130,6 +5237,7 @@ export const provide: {
* Effect.runPromise(runnable)
* // Example Output:
* // random number: 0.8241872233134417
+ * ```
*
* @since 2.0.0
* @category Context
@@ -5270,6 +5378,7 @@ export const updateService: {
* @see {@link let_ let}
*
* @example
+ * ```ts
* import { Effect, pipe } from "effect"
*
* const result = pipe(
@@ -5279,6 +5388,7 @@ export const updateService: {
* Effect.let("sum", ({ x, y }) => x + y)
* )
* assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
+ * ```
*
* @category Do notation
* @since 2.0.0
@@ -5300,6 +5410,7 @@ export const Do: Effect<{}> = effect.Do
* @see {@link let_ let}
*
* @example
+ * ```ts
* import { Effect, pipe } from "effect"
*
* const result = pipe(
@@ -5309,6 +5420,7 @@ export const Do: Effect<{}> = effect.Do
* Effect.let("sum", ({ x, y }) => x + y)
* )
* assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
+ * ```
*
* @category Do notation
* @since 2.0.0
@@ -5331,6 +5443,7 @@ export const bind: {
* results in a Do notation pipeline.
*
* @example
+ * ```ts
* import { Effect, Either, pipe } from "effect"
*
* const result = pipe(
@@ -5342,6 +5455,7 @@ export const bind: {
* }), { concurrency: 2, mode: "either" })
* )
* assert.deepStrictEqual(Effect.runSync(result), { x: 2, a: Either.right(2), b: Either.left("oops") })
+ * ```
*
* @category Do notation
* @since 3.7.0
@@ -5412,6 +5526,7 @@ export const bindAll: {
* @see {@link let_ let}
*
* @example
+ * ```ts
* import { Effect, pipe } from "effect"
*
* const result = pipe(
@@ -5421,6 +5536,7 @@ export const bindAll: {
* Effect.let("sum", ({ x, y }) => x + y)
* )
* assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
+ * ```
*
* @category Do notation
* @since 2.0.0
@@ -5458,6 +5574,7 @@ export {
* @see {@link bindTo}
*
* @example
+ * ```ts
* import { Effect, pipe } from "effect"
*
* const result = pipe(
@@ -5468,6 +5585,7 @@ export {
* )
* assert.deepStrictEqual(Effect.runSync(result), { x: 2, y: 3, sum: 5 })
*
+ * ```
* @category Do notation
* @since 2.0.0
*/
@@ -5492,6 +5610,7 @@ export {
* @see {@link exit} for a version that uses `Exit` instead.
*
* @example
+ * ```ts
* // Title: Using Effect.option to Handle Errors
* import { Effect } from "effect"
*
@@ -5524,6 +5643,7 @@ export {
* // _tag: 'Failure',
* // cause: { _id: 'Cause', _tag: 'Die', defect: 'Boom!' }
* // }
+ * ```
*
* @since 2.0.0
* @category Outcome Encapsulation
@@ -5549,6 +5669,7 @@ export const option: (self: Effect) => Effect
* @see {@link exit} for a version that uses `Exit` instead.
*
* @example
+ * ```ts
* import { Effect, Either, Random } from "effect"
*
* class HttpError {
@@ -5584,6 +5705,7 @@ export const option: (self: Effect) => Effect
* onRight: (value) => value // Do nothing in case of success
* })
* })
+ * ```
*
* @since 2.0.0
* @category Outcome Encapsulation
@@ -5607,6 +5729,7 @@ export const either: (self: Effect) => Effect(self: Effect) => Effect(self: Effect) => Effect, n
* failure. Additionally, if the effect is interrupted, the `Deferred` will also be interrupted.
*
* @example
+ * ```ts
* import { Deferred, Effect } from "effect"
*
* // Define an effect that succeeds
@@ -5678,6 +5803,7 @@ export const exit: (self: Effect) => Effect, n
* // Output:
* // 42
* // true
+ * ```
*
* @since 2.0.0
* @category Synchronization Utilities
@@ -5706,6 +5832,7 @@ export {
* is executed. If it is `false`, the `onFalse` effect is executed instead.
*
* @example
+ * ```ts
* // Title: Simulating a Coin Flip
* import { Effect, Random, Console } from "effect"
*
@@ -5716,6 +5843,7 @@ export {
*
* Effect.runFork(flipTheCoin)
*
+ * ```
* @since 2.0.0
* @category Conditional Operators
*/
@@ -5802,6 +5930,7 @@ export const filterOrElse: {
* Let's explore this concept through an example:
*
* @example
+ * ```ts
* import { Effect, pipe } from "effect"
*
* // Define a user interface
@@ -5822,6 +5951,7 @@ export const filterOrElse: {
* // 'user' now has the type `User` (not `User | null`)
* Effect.andThen((user) => user.name)
* )
+ * ```
*
* @since 2.0.0
* @category Filtering
@@ -5900,6 +6030,7 @@ export const unlessEffect: {
* @see {@link unless} for a version that executes the effect when the condition is `false`.
*
* @example
+ * ```ts
* // Title: Conditional Effect Execution
* import { Effect, Option } from "effect"
*
@@ -5925,6 +6056,7 @@ export const unlessEffect: {
* // _id: "Option",
* // _tag: "None"
* // }
+ * ```
*
* @since 2.0.0
* @category Conditional Operators
@@ -5952,6 +6084,7 @@ export const when: {
* @see {@link unlessEffect} for a version that executes the effect when the condition is `false`.
*
* @example
+ * ```ts
* // Title: Using an Effect as a Condition
* import { Effect, Random } from "effect"
*
@@ -5962,6 +6095,7 @@ export const when: {
* console.log(Effect.runSync(randomIntOption))
* // Example Output:
* // { _id: 'Option', _tag: 'Some', value: 8609104974198840 }
+ * ```
*
* @since 2.0.0
* @category Conditional Operators
@@ -6033,6 +6167,7 @@ export const whenRef: {
* changing the original one.
*
* @example
+ * ```ts
* import { pipe, Effect } from "effect"
*
* // Function to apply a discount safely to a transaction amount
@@ -6055,6 +6190,7 @@ export const whenRef: {
*
* Effect.runPromise(finalAmount).then(console.log)
* // Output: 95
+ * ```
*
* @since 2.0.0
* @category sequencing
@@ -6098,6 +6234,7 @@ export const flatMap: {
* treating them as effects.
*
* @example
+ * ```ts
* // Title: Applying a Discount Based on Fetched Amount
* import { pipe, Effect } from "effect"
*
@@ -6132,6 +6269,7 @@ export const flatMap: {
*
* Effect.runPromise(result2).then(console.log)
* // Output: 190
+ * ```
*
* @since 2.0.0
* @category sequencing
@@ -6281,6 +6419,7 @@ export const summarized: {
* will fail too.
*
* @example
+ * ```ts
* // Title: Logging a step in a pipeline
* import { Console, Effect, pipe } from "effect"
*
@@ -6308,6 +6447,7 @@ export const summarized: {
* // Output:
* // Apply a discount to: 100
* // 95
+ * ```
*
* @since 2.0.0
* @category sequencing
@@ -6375,6 +6515,7 @@ export const tap: {
* altering the result.
*
* @example
+ * ```ts
* import { Effect, Random, Console } from "effect"
*
* // Simulate a task that might fail
@@ -6394,6 +6535,7 @@ export const tap: {
* Effect.runFork(tapping)
* // Example Output:
* // failure: random number is negative
+ * ```
*
* @since 2.0.0
* @category sequencing
@@ -6425,6 +6567,7 @@ export const tapBoth: {
* severe errors.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* // Simulate a task that fails with a recoverable error
@@ -6452,6 +6595,7 @@ export const tapBoth: {
* // Output:
* // defect: RuntimeException: Something went wrong
* // ... stack trace ...
+ * ```
*
* @since 2.0.0
* @category sequencing
@@ -6476,6 +6620,7 @@ export const tapDefect: {
* while the operation you provide can inspect or act on it.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* // Simulate a task that fails with an error
@@ -6489,6 +6634,7 @@ export const tapDefect: {
* Effect.runFork(tapping)
* // Output:
* // expected error: NetworkError
+ * ```
*
* @since 2.0.0
* @category sequencing
@@ -6510,6 +6656,7 @@ export const tapError: {
* without modifying the error or the overall result of the effect.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* class NetworkError {
@@ -6534,6 +6681,7 @@ export const tapError: {
* Effect.runFork(tapping)
* // Output:
* // expected error: 504
+ * ```
*
* @since 2.0.0
* @category sequencing
@@ -6560,6 +6708,7 @@ export const tapErrorTag: {
* altering the error or the overall result of the effect.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* // Create a task that fails with a NetworkError
@@ -6586,6 +6735,7 @@ export const tapErrorTag: {
* // Output:
* // error cause: RuntimeException: Something went wrong
* // ... stack trace ...
+ * ```
*
* @since 2.0.0
* @category sequencing
@@ -6627,6 +6777,7 @@ export const forever: (self: Effect) => Effect =
* ```
*
* @example
+ * ```ts
* // Title: Effectful Iteration
* import { Effect } from "effect"
*
@@ -6643,6 +6794,7 @@ export const forever: (self: Effect) => Effect =
*
* Effect.runPromise(result).then(console.log)
* // Output: 6
+ * ```
*
* @since 2.0.0
* @category Looping
@@ -6691,6 +6843,7 @@ export const iterate: {
* discarded, and the final result will be `void`.
*
* @example
+ * ```ts
* // Title: Looping with Collected Results
* import { Effect } from "effect"
*
@@ -6710,6 +6863,7 @@ export const iterate: {
*
* Effect.runPromise(result).then(console.log)
* // Output: [1, 2, 3, 4, 5]
+ * ```
*
* @example
* // Title: Loop with Discarded Results
@@ -6823,6 +6977,7 @@ export declare namespace Repeat {
* an additional time.
*
* @example
+ * ```ts
* // Success Example
* import { Effect, Schedule, Console } from "effect"
*
@@ -6831,6 +6986,7 @@ export declare namespace Repeat {
* const program = Effect.repeat(action, policy)
*
* Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
+ * ```
*
* @example
* // Failure Example
@@ -6881,12 +7037,14 @@ export const repeat: {
* initially and then repeats it one additional time if it succeeds.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* const action = Console.log("success")
* const program = Effect.repeatN(action, 2)
*
* Effect.runPromise(program)
+ * ```
*
* @since 2.0.0
* @category repetition / recursion
@@ -6905,6 +7063,7 @@ export const repeatN: {
* initially and then repeats it an additional time if it succeeds.
*
* @example
+ * ```ts
* import { Effect, Schedule } from "effect"
*
* let count = 0
@@ -6934,6 +7093,7 @@ export const repeatN: {
* )
*
* Effect.runPromise(program).then((n) => console.log(`repetitions: ${n}`))
+ * ```
*
* @since 2.0.0
* @category repetition / recursion
@@ -7123,6 +7283,7 @@ export const isSuccess: (self: Effect) => Effect = Effect.succeed(42)
@@ -7148,6 +7309,7 @@ export const isSuccess: (self: Effect) => Effect = Effect.die("Uh oh!")
@@ -7240,6 +7403,7 @@ export const matchCause: {
*
* Effect.runSync(program)
* // Output: "Die: Uh oh!"
+ * ```
*
* @since 2.0.0
* @category getters & folding
@@ -7298,6 +7462,7 @@ export const matchEffect: {
* To adjust the log level, use the `Logger.withMinimumLogLevel` function.
*
* @example
+ * ```ts
* import { Cause, Effect } from "effect"
*
* const program = Effect.log(
@@ -7311,6 +7476,7 @@ export const matchEffect: {
* // Output:
* // timestamp=... level=INFO fiber=#0 message=message1 message=message2 cause="Error: Oh no!
* // Error: Oh uh!"
+ * ```
*
* @since 2.0.0
* @category Logging
@@ -7344,12 +7510,14 @@ export const logTrace: (...message: ReadonlyArray) => Effect) => Effect) => Effect(self: Effect) => Effect = co
* @see {@link orDie} if you don't need to customize the error.
*
* @example
+ * ```ts
* // Title: Customizing Defect
* import { Effect } from "effect"
*
@@ -7563,6 +7740,7 @@ export const orDie: (self: Effect) => Effect = co
* // Output:
* // (FiberFailure) Error: defect: Cannot divide by zero
* // ...stack trace...
+ * ```
*
* @since 2.0.0
* @category Converting Failures to Defects
@@ -7583,6 +7761,7 @@ export const orDieWith: {
* @see {@link catchAll} if you need to access the error in the fallback effect.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const success = Effect.succeed("success")
@@ -7598,6 +7777,7 @@ export const orDieWith: {
* const program2 = Effect.orElse(failure, () => fallback)
* console.log(Effect.runSync(program2))
* // Output: "fallback"
+ * ```
*
* @since 2.0.0
* @category Fallback
@@ -7620,6 +7800,7 @@ export const orElse: {
* @see {@link mapError} if you need to access the error to transform it.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const validate = (age: number): Effect.Effect => {
@@ -7641,6 +7822,7 @@ export const orElse: {
* // _tag: 'Failure',
* // cause: { _id: 'Cause', _tag: 'Fail', failure: 'invalid age' }
* // }
+ * ```
*
* @since 2.0.0
* @category Fallback
@@ -7668,6 +7850,7 @@ export const orElseFail: {
* already succeeds, it will remain unchanged.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const validate = (age: number): Effect.Effect => {
@@ -7685,6 +7868,7 @@ export const orElseFail: {
* console.log(Effect.runSyncExit(program))
* // Output:
* // { _id: 'Exit', _tag: 'Success', value: 18 }
+ * ```
*
* @since 2.0.0
* @category Fallback
@@ -7712,6 +7896,7 @@ export const orElseSucceed: {
* error.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* interface Config {
@@ -7758,6 +7943,7 @@ export const orElseSucceed: {
* // Unavailable config for node2
* // Config for node3 found
* // { host: 'node3.example.com', port: 8080, apiKey: '12345-abcde' }
+ * ```
*
* @since 2.0.0
* @category Fallback
@@ -7998,6 +8184,7 @@ export const unsafeMakeLatch: (open?: boolean | undefined) => Latch = circular.u
* @category latch
* @since 3.8.0
* @example
+ * ```ts
* import { Effect } from "effect"
*
* Effect.gen(function*() {
@@ -8014,6 +8201,7 @@ export const unsafeMakeLatch: (open?: boolean | undefined) => Latch = circular.u
* yield* latch.open
* yield* fiber.await
* })
+ * ```
*/
export const makeLatch: (open?: boolean | undefined) => Effect = circular.makeLatch
@@ -8031,6 +8219,7 @@ export const makeLatch: (open?: boolean | undefined) => Effect Effect {
* Effect.runFork(Fiber.interrupt(fiber))
* }, 500)
+ * ```
*
* @since 2.0.0
* @category Running Effects
@@ -8081,11 +8271,13 @@ export const runCallback: (
* @see {@link runPromiseExit} for a version that returns an `Exit` type instead of rejecting.
*
* @example
+ * ```ts
* // Title: Running a Successful Effect as a Promise
* import { Effect } from "effect"
*
* Effect.runPromise(Effect.succeed(1)).then(console.log)
* // Output: 1
+ * ```
*
* @example
* //Example: Handling a Failing Effect as a Rejected Promise
@@ -8120,6 +8312,7 @@ export const runPromise: (
* a `Cause` type.
*
* @example
+ * ```ts
* // Title: Handling Results as Exit
* import { Effect } from "effect"
*
@@ -8144,6 +8337,7 @@ export const runPromise: (
* // failure: "my error"
* // }
* // }
+ * ```
*
* @since 2.0.0
* @category Running Effects
@@ -8169,6 +8363,7 @@ export const runPromiseExit: (
* throwing an error.
*
* @example
+ * ```ts
* // Title: Synchronous Logging
* import { Effect } from "effect"
*
@@ -8182,6 +8377,7 @@ export const runPromiseExit: (
*
* console.log(result)
* // Output: 1
+ * ```
*
* @example
* // Title: Incorrect Usage with Failing or Async Effects
@@ -8231,6 +8427,7 @@ export const runSync: (effect: Effect) => A = _runtime.unsafeRunSync
* resolved synchronously.
*
* @example
+ * ```ts
* // Title: Handling Results as Exit
* import { Effect } from "effect"
*
@@ -8253,6 +8450,7 @@ export const runSync: (effect: Effect) => A = _runtime.unsafeRunSync
* // failure: "my error"
* // }
* // }
+ * ```
*
* @example
* // Title: Asynchronous Operation Resulting in Die
@@ -8294,6 +8492,7 @@ export const runSyncExit: (effect: Effect) => Exit.Exit = _run
* @see {@link zip} for a version that stops at the first error.
*
* @example
+ * ```ts
* import { Effect, Console } from "effect"
*
* const task1 = Console.log("task1").pipe(Effect.as(1))
@@ -8321,6 +8520,7 @@ export const runSyncExit: (effect: Effect) => Exit.Exit = _run
* // right: { _id: 'Cause', _tag: 'Fail', failure: 'Oh no!' }
* // }
* // }
+ * ```
*
* @since 2.0.0
* @category Error Accumulation
@@ -8395,6 +8595,7 @@ export const validateWith: {
* @see {@link validate} for a version that accumulates errors.
*
* @example
+ * ```ts
* // Title: Combining Two Effects Sequentially
* import { Effect } from "effect"
*
@@ -8418,6 +8619,7 @@ export const validateWith: {
* // timestamp=... level=INFO fiber=#0 message="task1 done"
* // timestamp=... level=INFO fiber=#0 message="task2 done"
* // [ 1, 'hello' ]
+ * ```
*
* @example
* // Title: Combining Two Effects Concurrently
@@ -8486,6 +8688,7 @@ export const zip: {
* @see {@link zipRight} for a version that returns the result of the second effect.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const task1 = Effect.succeed(1).pipe(
@@ -8504,6 +8707,7 @@ export const zip: {
* // timestamp=... level=INFO fiber=#0 message="task1 done"
* // timestamp=... level=INFO fiber=#0 message="task2 done"
* // 1
+ * ```
*
* @since 2.0.0
* @category Zipping
@@ -8550,6 +8754,7 @@ export const zipLeft: {
* @see {@link zipLeft} for a version that returns the result of the first effect.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const task1 = Effect.succeed(1).pipe(
@@ -8568,6 +8773,7 @@ export const zipLeft: {
* // timestamp=... level=INFO fiber=#0 message="task1 done"
* // timestamp=... level=INFO fiber=#0 message="task2 done"
* // hello
+ * ```
*
* @since 2.0.0
* @category Zipping
@@ -8608,6 +8814,7 @@ export const zipRight: {
* use the `{ concurrent: true }` option.
*
* @example
+ * ```ts
* // Title: Combining Effects with a Custom Function
* import { Effect } from "effect"
*
@@ -8632,6 +8839,7 @@ export const zipRight: {
* // timestamp=... level=INFO fiber=#3 message="task1 done"
* // timestamp=... level=INFO fiber=#2 message="task2 done"
* // 6
+ * ```
*
* @since 2.0.0
* @category Zipping
@@ -8787,6 +8995,7 @@ export const withTracerScoped: (value: Tracer.Tracer) => Effect Effect(effect: Effect) => Effect
@@ -8960,6 +9170,7 @@ export interface FunctionWithSpanOptions {
* @since 3.2.0
* @category Tracing
* @example
+ * ```ts
* import { Effect } from "effect"
*
* const getTodo = Effect.functionWithSpan({
@@ -8969,6 +9180,7 @@ export interface FunctionWithSpanOptions {
* attributes: { id }
* })
* })
+ * ```
*/
export const functionWithSpan: , Ret extends Effect>(
options: {
@@ -9021,6 +9233,7 @@ export const withParentSpan: {
* value.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* // ┌─── Effect
@@ -9046,6 +9259,7 @@ export const withParentSpan: {
* // failure: { _tag: 'NoSuchElementException' }
* // }
* // }
+ * ```
*
* @since 2.0.0
* @category Optional Wrapping
@@ -9064,6 +9278,7 @@ export const fromNullable: (value: A) => Effect, Cause.NoSuchE
* unchanged.
*
* @example
+ * ```ts
* import { Effect } from "effect"
*
* // ┌─── Effect
@@ -9087,6 +9302,7 @@ export const fromNullable: (value: A) => Effect, Cause.NoSuchE
*
* Effect.runPromise(option2).then(console.log)
* // Output: { _tag: 'None' }
+ * ```
*
* @since 2.0.0
* @category Optional Wrapping
@@ -9173,6 +9389,7 @@ const makeTagProxy = (TagClass: Context.Tag & Record
/**
* @example
+ * ```ts
* import { Effect, Layer } from "effect"
*
* class MapTag extends Effect.Tag("MapTag")>() {
@@ -9181,6 +9398,7 @@ const makeTagProxy = (TagClass: Context.Tag & Record
* Effect.sync(() => new Map())
* )
* }
+ * ```
*
* @since 2.0.0
* @category Context
@@ -9220,6 +9438,7 @@ export const Tag: