feat: add examples for transpose

yifanwww · Mar 23, 2024 · 2226e55 · 2226e55
1 parent 3d6f6f4
commit 2226e55
Show file tree

Hide file tree

Showing 4 changed files with 140 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -11,41 +11,42 @@ Rust-like `Result` for JavaScript.
 - [About Rust `Option`](#about-rust-option)
 - [Methods Documentation](#methods-documentation)
   - [Rust `Result` Methods](#rust-result-methods)
-    - [isOk](#isok)
-    - [isOkAnd](#isokand)
-    - [isOkAndAsync](#isokandasync)
-    - [isErr](#iserr)
-    - [isErrAnd](#iserrand)
-    - [isErrAndAsync](#iserrandasync)
-    - [ok](#ok)
-    - [err](#err)
-    - [map](#map)
-    - [mapAsync](#mapasync)
-    - [mapOr](#mapor)
-    - [mapOrAsync](#maporasync)
-    - [mapOrElse](#maporelse)
-    - [mapOrElseAsync](#maporelseasync)
-    - [mapErr](#maperr)
-    - [mapErrAsync](#maperrasync)
-    - [inspect](#inspect)
-    - [inspectAsync](#inspectasync)
-    - [inspectErr](#inspecterr)
-    - [inspectErrAsync](#inspecterrasync)
-    - [expect](#expect)
-    - [unwrap](#unwrap)
-    - [expectErr](#expecterr)
-    - [unwrapErr](#unwraperr)
-    - [unwrapOr](#unwrapor)
-    - [unwrapOrElse](#unwraporelse)
-    - [unwrapOrElseAsync](#unwraporelseasync)
-    - [unwrapUnchecked](#unwrapunchecked)
-    - [unwrapErrUnchecked](#unwraperrunchecked)
-    - [and](#and)
-    - [andThen](#andthen)
-    - [andThenAsync](#andthenasync)
-    - [or](#or)
-    - [orElse](#orelse)
-    - [orElseAsync](#orelseasync)
+    - [`isOk`](#isok)
+    - [`isOkAnd`](#isokand)
+    - [`isOkAndAsync`](#isokandasync)
+    - [`isErr`](#iserr)
+    - [`isErrAnd`](#iserrand)
+    - [`isErrAndAsync`](#iserrandasync)
+    - [`ok`](#ok)
+    - [`err`](#err)
+    - [`map`](#map)
+    - [`mapAsync`](#mapasync)
+    - [`mapOr`](#mapor)
+    - [`mapOrAsync`](#maporasync)
+    - [`mapOrElse`](#maporelse)
+    - [`mapOrElseAsync`](#maporelseasync)
+    - [`mapErr`](#maperr)
+    - [`mapErrAsync`](#maperrasync)
+    - [`inspect`](#inspect)
+    - [`inspectAsync`](#inspectasync)
+    - [`inspectErr`](#inspecterr)
+    - [`inspectErrAsync`](#inspecterrasync)
+    - [`expect`](#expect)
+    - [`unwrap`](#unwrap)
+    - [`expectErr`](#expecterr)
+    - [`unwrapErr`](#unwraperr)
+    - [`unwrapOr`](#unwrapor)
+    - [`unwrapOrElse`](#unwraporelse)
+    - [`unwrapOrElseAsync`](#unwraporelseasync)
+    - [`unwrapUnchecked`](#unwrapunchecked)
+    - [`unwrapErrUnchecked`](#unwraperrunchecked)
+    - [`and`](#and)
+    - [`andThen`](#andthen)
+    - [`andThenAsync`](#andthenasync)
+    - [`or`](#or)
+    - [`orElse`](#orelse)
+    - [`orElseAsync`](#orelseasync)
+    - [`transpose`](#transpose)
   - [Additional Methods](#additional-methods)
     - [equal](#equal)
 - [Helpers for Resultifying](#helpers-for-resultifying)
@@ -861,6 +862,35 @@ const z = await Err<number, number>(3)
 assert(z.equal(Err(3)));
 ```
 
+#### `transpose`
+
+Transposes a `Result` of an optional value into an optional of a `Result`.
+
+`Ok(undefined | null)` will be mapped to `undefined`. `Ok(_)` and `Err(_)` will be mapped to `Ok(_)` and `Err(_)`.
+
+Examples:
+
+```ts
+import { Err, Ok, type Result } from 'rustlike-result';
+
+type SomeErr = unknown;
+
+let x: Result<number | undefined | null, SomeErr>;
+let y: Result<number, SomeErr> | undefined;
+
+x = Ok(5);
+y = Ok(5);
+assert(x.transpose()!.equal(y));
+
+x = Ok(undefined);
+y = undefined;
+assert(x.transpose() === y);
+
+x = Ok(null);
+y = undefined;
+assert(x.transpose() === y);
+```
+
 ### Additional Methods
 #### equal
 

diff --git a/src/__tests__/result.test.ts b/src/__tests__/result.test.ts
@@ -1485,6 +1485,29 @@ describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.protot
             Err('Some error message'),
         );
     });
+
+    it('should have correct examples doc', () => {
+        function examples() {
+            type SomeErr = unknown;
+
+            let x: Result<number | undefined | null, SomeErr>;
+            let y: Result<number, SomeErr> | undefined;
+
+            x = Ok(5);
+            y = Ok(5);
+            assert(x.transpose()!.equal(y));
+
+            x = Ok(undefined);
+            y = undefined;
+            assert(x.transpose() === y);
+
+            x = Ok(null);
+            y = undefined;
+            assert(x.transpose() === y);
+        }
+
+        expect(examples).not.toThrow();
+    });
 });
 
 describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.prototype.equal.name}\``, () => {

diff --git a/src/result.ts b/src/result.ts
@@ -929,9 +929,32 @@ export class RustlikeResult<T, E> implements Result<T, E> {
 
     /**
      * Transposes a `Result` of an optional value into an optional of a `Result`.
-     * - `Ok(undefined | null)` will be mapped to `undefined`.
-     * - `Ok(_)` (`Ok(Some(_))` in Rust) will be mapped to `Ok(_)` (`Some(Ok(_))` in Rust).
-     * - `Err(_)` will be mapped to `Err(_)` (`Some(Err(_))` in Rust).
+     *
+     * `Ok(undefined | null)` will be mapped to `undefined`.
+     * `Ok(_)` and `Err(_)` will be mapped to `Ok(_)` and `Err(_)`.
+     *
+     * Examples:
+     *
+     * ```
+     * import { Err, Ok, type Result } from 'rustlike-result';
+     *
+     * type SomeErr = unknown;
+     *
+     * let x: Result<number | undefined | null, SomeErr>;
+     * let y: Result<number, SomeErr> | undefined;
+     *
+     * x = Ok(5);
+     * y = Ok(5);
+     * assert(x.transpose()!.equal(y));
+     *
+     * x = Ok(undefined);
+     * y = undefined;
+     * assert(x.transpose() === y);
+     *
+     * x = Ok(null);
+     * y = undefined;
+     * assert(x.transpose() === y);
+     * ```
      *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.transpose
      */

diff --git a/src/types.ts b/src/types.ts
@@ -811,9 +811,32 @@ export interface Result<T, E> {
 
     /**
      * Transposes a `Result` of an optional value into an optional of a `Result`.
-     * - `Ok(undefined | null)` will be mapped to `undefined`.
-     * - `Ok(_)` (`Ok(Some(_))` in Rust) will be mapped to `Ok(_)` (`Some(Ok(_))` in Rust).
-     * - `Err(_)` will be mapped to `Err(_)` (`Some(Err(_))` in Rust).
+     *
+     * `Ok(undefined | null)` will be mapped to `undefined`.
+     * `Ok(_)` and `Err(_)` will be mapped to `Ok(_)` and `Err(_)`.
+     *
+     * Examples:
+     *
+     * ```
+     * import { Err, Ok, type Result } from 'rustlike-result';
+     *
+     * type SomeErr = unknown;
+     *
+     * let x: Result<number | undefined | null, SomeErr>;
+     * let y: Result<number, SomeErr> | undefined;
+     *
+     * x = Ok(5);
+     * y = Ok(5);
+     * assert(x.transpose()!.equal(y));
+     *
+     * x = Ok(undefined);
+     * y = undefined;
+     * assert(x.transpose() === y);
+     *
+     * x = Ok(null);
+     * y = undefined;
+     * assert(x.transpose() === y);
+     * ```
      *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.transpose
      */