Skip to content

Commit 22cb7e2

Browse files
richecrrichecr
committed
docs: enhances Either, Maybe, and Result documentation
Improves clarity and completeness of method descriptions Adds examples for key functionalities in Either, Maybe, and Result types Introduces new equals methods for better comparison capabilities
1 parent 7b0385c commit 22cb7e2

File tree

3 files changed

+458
-21
lines changed

3 files changed

+458
-21
lines changed

‎docs/either/index.md‎

Lines changed: 224 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
```ts
66
import { Right } from 'holo-fn/either'
77

8-
const result = new Right<number, number>(10)
8+
const result = new Right(10)
99
.map(n => n * 2)
1010
.unwrapOr(0)
1111

@@ -14,27 +14,226 @@ console.log(result); // 20
1414

1515
## Methods
1616

17-
### `map(fn: (value: R) => U): Either<L, U>`
17+
##### `map(fn: (value: R) => U): Either<L, U>`
1818
Maps over the `Right` value. Does nothing for `Left`.
1919

20-
### `mapLeft<M>(fn: (err: L) => M): Either<M, R>`
20+
```ts
21+
import { Either, Left, Right } from "holo-fn/either";
22+
23+
const calculate = (a: number, b: number): Either<string, number> => {
24+
if (b === 0) {
25+
return new Left("Division by zero");
26+
}
27+
28+
return new Right(a / b);
29+
};
30+
31+
const result1 = calculate(10, 2)
32+
.map(n => n * 2)
33+
.unwrapOr(0);
34+
35+
console.log(result1); // 10
36+
37+
const result2 = calculate(10, 0)
38+
.map(n => n * 2)
39+
.unwrapOr(0);
40+
41+
console.log(result2); // 0
42+
```
43+
44+
##### `mapLeft<M>(fn: (err: L) => M): Either<M, R>`
2145
Maps over the `Left` value. Does nothing for `Right`.
2246

23-
### `chain(fn: (value: R) => Either<L, U>): Either<L, U>`
47+
```ts
48+
import { Either, Left, Right } from "holo-fn/either";
49+
50+
const calculate = (a: number, b: number): Either<string, number> => {
51+
if (b === 0) {
52+
return new Left("Division by zero");
53+
}
54+
55+
return new Right(a / b);
56+
};
57+
58+
const result1 = calculate(10, 2)
59+
.map(n => n * 2)
60+
.mapLeft(e => console.log(`Error: ${e}`)) // No printing here
61+
.unwrapOr(0);
62+
63+
console.log(result1); // 10
64+
65+
const result2 = calculate(10, 0)
66+
.map(n => n * 2)
67+
.mapLeft(e => console.log(`Error: ${e}`)) // Prints "Error: Division by zero"
68+
.unwrapOr(0);
69+
70+
console.log(result2); // 0
71+
```
72+
73+
##### `chain(fn: (value: R) => Either<L, U>): Either<L, U>`
2474
Chains the transformation if the value is `Right`. Returns `Left` otherwise.
2575

26-
### `unwrapOr(defaultValue: R): R`
76+
```ts
77+
import { Either, Left, Right } from "holo-fn/either";
78+
79+
const calculate = (a: number, b: number): Either<string, number> => {
80+
if (b === 0) {
81+
return new Left("Division by zero");
82+
}
83+
84+
return new Right(a / b);
85+
};
86+
87+
const result1 = calculate(12, 2)
88+
.chain(n => n > 5 ? new Right(n * 2) : new Left("Result is too small"))
89+
.map(n => n + 1)
90+
.mapLeft(e => console.log(`Error: ${e}`)) // Not run
91+
.unwrapOr(0);
92+
93+
94+
console.log(result1); // 13
95+
96+
const result2 = calculate(10, 2)
97+
.chain(n => n > 5 ? new Right(n * 2) : new Left("Result is too small"))
98+
.map(n => n + 1)
99+
.mapLeft(e => console.log(`Error: ${e}`)) // Prints "Error: Result is too small"
100+
.unwrapOr(0);
101+
102+
console.log(result2); // 0
103+
```
104+
105+
##### `unwrapOr(defaultValue: R): R`
27106
Returns the value of `Right`, or the default value for `Left`.
28107

29-
### `isRight(): boolean`
108+
```ts
109+
import { Either, Left, Right } from "holo-fn/either";
110+
111+
const calculate = (a: number, b: number): Either<string, number> => {
112+
if (b === 0) {
113+
return new Left("Division by zero");
114+
}
115+
116+
return new Right(a / b);
117+
};
118+
119+
const result1 = calculate(12, 2).unwrapOr(0);
120+
console.log(result1); // 6
121+
122+
const result2 = calculate(10, 0).unwrapOr(-1);
123+
console.log(result2); // -1
124+
```
125+
126+
##### `isRight(): boolean`
30127
Checks if the value is `Right`.
31128

32-
### `isLeft(): boolean`
129+
```ts
130+
import { Either, Left, Right } from "holo-fn/either";
131+
132+
const calculate = (a: number, b: number): Either<string, number> => {
133+
if (b === 0) {
134+
return new Left("Division by zero");
135+
}
136+
137+
return new Right(a / b);
138+
};
139+
140+
const result1 = calculate(12, 2).isRight();
141+
console.log(result1); // true
142+
143+
const result2 = calculate(10, 0).isRight();
144+
console.log(result2); // false
145+
```
146+
147+
##### `isLeft(): boolean`
33148
Checks if the value is `Left`.
34149

35-
### `match<T>(cases: { left: (left: L) => T; right: (right: R) => T }): T`
150+
```ts
151+
import { Either, Left, Right } from "holo-fn/either";
152+
153+
const calculate = (a: number, b: number): Either<string, number> => {
154+
if (b === 0) {
155+
return new Left("Division by zero");
156+
}
157+
158+
return new Right(a / b);
159+
};
160+
161+
const result1 = calculate(12, 2).isLeft();
162+
console.log(result1); // false
163+
164+
const result2 = calculate(10, 0).isLeft();
165+
console.log(result2); // true
166+
```
167+
168+
##### `match<T>(cases: { left: (left: L) => T; right: (right: R) => T }): T`
36169
Matches the value to execute either the `left` or `right` case.
37170

171+
```ts
172+
import { Either, Left, Right } from "holo-fn/either";
173+
174+
const calculate = (a: number, b: number): Either<string, number> => {
175+
if (b === 0) {
176+
return new Left("Division by zero");
177+
}
178+
179+
return new Right(a / b);
180+
};
181+
182+
const result1 = calculate(12, 2)
183+
.chain(n => n > 5 ? new Right(n * 2) : new Left("Result is too small"))
184+
.map(n => n + 1)
185+
.match({
186+
right: n => n,
187+
left: e => {
188+
console.log(`Error: ${e}`); // Not run
189+
return 0;
190+
}
191+
});
192+
193+
console.log(result1); // 13
194+
195+
const result2 = calculate(10, 2)
196+
.chain(n => n > 5 ? new Right(n * 2) : new Left("Result is too small"))
197+
.map(n => n + 1)
198+
.match({
199+
right: n => n,
200+
left: e => {
201+
console.log(`Error: ${e}`); // Prints "Error: Result is too small"
202+
return 0;
203+
}
204+
});
205+
206+
console.log(result2); // 0
207+
```
208+
209+
##### `equals(other: Either<L, R>): boolean`
210+
Compares `this` to another `Either`, returns `false` if the values inside are different.
211+
212+
```ts
213+
import { Either, Left, Right } from "holo-fn/either";
214+
215+
const calculate = (a: number, b: number): Either<string, number> => {
216+
if (b === 0) {
217+
return new Left("Division by zero");
218+
}
219+
220+
return new Right(a / b);
221+
};
222+
223+
const result1 = calculate(12, 2)
224+
.chain(n => n > 5 ? new Right(n * 2) : new Left("Result is too small"))
225+
.map(n => n + 1);
226+
227+
console.log(result1.equals(new Right(13))); // true
228+
229+
const result2 = calculate(10, 2)
230+
.chain(n => n > 5 ? new Right(n * 2) : new Left("Result is too small"))
231+
.map(n => n + 1);
232+
233+
console.log(result2.equals(new Right(0))); // false
234+
235+
```
236+
38237
## Helpers
39238

40239
### `tryCatch(fn, onError?)`
@@ -186,3 +385,20 @@ console.log(result); // "Success: 10"
186385
```
187386

188387
---
388+
389+
### `equalsE`
390+
391+
Curried version of `equals` for `Either`. Compares `this` to another `Either`, returns `false` if the values inside are different.
392+
393+
```ts
394+
import { equalsE, Right } from 'holo-fn/either';
395+
396+
const result = pipe(
397+
new Right(10),
398+
equalsE(new Right(10))
399+
);
400+
401+
console.log(result); // true
402+
```
403+
404+
---

‎docs/maybe/index.md‎

Lines changed: 105 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,24 +14,106 @@ console.log(name) // RICH
1414

1515
## Methods
1616

17-
### `map(fn: (value: T) => U): Maybe<U>`
17+
##### `map(fn: (value: T) => U): Maybe<U>`
1818
Maps over the `Just` value. Does nothing for `Nothing`.
1919

20-
### `chain(fn: (value: T) => Maybe<U>): Maybe<U>`
20+
```ts
21+
import { Just, Nothing } from "holo-fn/maybe";
22+
23+
const result1 = new Just(5).map((n) => n * 2);
24+
console.log(result1.unwrapOr(0)); // 10
25+
26+
const result2 = new Nothing<number>().map((n) => n * 2);
27+
console.log(result2.unwrapOr(0)); // 0
28+
```
29+
30+
##### `chain(fn: (value: T) => Maybe<U>): Maybe<U>`
2131
Chains the transformation if the value is `Just`. Returns `Nothing` otherwise.
2232

23-
### `unwrapOr(defaultValue: T): T`
33+
```ts
34+
import { Just, Nothing } from "holo-fn/maybe";
35+
36+
const result1 = new Just(5).chain((n) => new Just(n * 2));
37+
console.log(result1.unwrapOr(0)); // 10
38+
39+
const result2 = new Nothing<number>().chain((n) => new Just(n * 2));
40+
console.log(result2.unwrapOr(0)); // 0
41+
```
42+
43+
##### `unwrapOr(defaultValue: T): T`
2444
Returns the value of `Just`, or the default value for `Nothing`.
2545

26-
### `isJust(): boolean`
46+
```ts
47+
import { Just, Nothing } from "holo-fn/maybe";
48+
49+
const result1 = new Just(10);
50+
console.log(result1.unwrapOr(0)); // 10
51+
52+
const result2 = new Nothing<number>();
53+
console.log(result2.unwrapOr(0)); // 0
54+
```
55+
56+
##### `isJust(): boolean`
2757
Checks if the value is `Just`.
2858

29-
### `isNothing(): boolean`
59+
```ts
60+
import { Just, Nothing } from "holo-fn/maybe";
61+
62+
const result1 = new Just("value");
63+
console.log(result1.isJust()); // true
64+
65+
const result2 = new Nothing();
66+
console.log(result2.isJust()); // false
67+
```
68+
69+
##### `isNothing(): boolean`
3070
Checks if the value is `Nothing`.
3171

32-
### `match<U>(cases: { just: (value: T) => U; nothing: () => U }): U`
72+
```ts
73+
import { Just, Nothing } from "holo-fn/maybe";
74+
75+
const result1 = new Just("value");
76+
console.log(result1.isNothing()); // false
77+
78+
const result2 = new Nothing();
79+
console.log(result2.isNothing()); // true
80+
```
81+
82+
##### `match<U>(cases: { just: (value: T) => U; nothing: () => U }): U`
3383
Matches the value to execute either the `just` or `nothing` case.
3484

85+
```ts
86+
import { Just, Nothing } from "holo-fn/maybe";
87+
88+
const result1 = new Just("value").match({
89+
just: (v) => `Has value: ${v}`,
90+
nothing: () => "No value",
91+
});
92+
console.log(result1); // "Has value: value"
93+
94+
const result2 = new Nothing().match({
95+
just: (v) => `Has value: ${v}`,
96+
nothing: () => "No value",
97+
});
98+
console.log(result2); // "No value"
99+
```
100+
101+
##### `equals(other: Maybe<T>): boolean`
102+
Compares the values inside `this` and the other, returns `true` if both are `Nothing` or if the values are equal.
103+
104+
```ts
105+
import { Just, Nothing } from "holo-fn/maybe";
106+
107+
const result1 = new Just("value").chain(v => new Just(v + " modified"));
108+
109+
console.log(result1.equals(new Just("value"))); // false
110+
console.log(result1.equals(new Just("value modified"))); // true
111+
112+
const result2 = new Just("value").chain(v => new Nothing());
113+
console.log(result2.equals(new Nothing())); // true
114+
console.log(result2.equals(new Just("value"))); // false
115+
```
116+
35117
## Helpers
36118

37119
### `fromNullable(value)`
@@ -121,3 +203,20 @@ console.log(result); // "Got hello"
121203
```
122204

123205
---
206+
207+
### `equalsM`
208+
209+
Curried version of `equals` for `Maybe`. Compares the values inside `this` and the other, returns `true` if both are `Nothing` or if the values are equal.
210+
211+
```ts
212+
import { equalsM, Just } from 'holo-fn/maybe';
213+
214+
const result = pipe(
215+
new Just(10),
216+
equalsM(new Just(10))
217+
);
218+
219+
console.log(result); // true
220+
```
221+
222+
---

0 commit comments

Comments
 (0)