feat: add examples for inspect, inspectAsync, inspectErr, inspectErrA…

…sync
yifanwww · Mar 23, 2024 · 1a44c57 · 1a44c57
1 parent 0822941
commit 1a44c57
Show file tree

Hide file tree

Showing 4 changed files with 251 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -27,6 +27,10 @@ Rust-like `Result` for JavaScript.
     - [mapOrElseAsync](#maporelseasync)
     - [mapErr](#maperr)
     - [mapErrAsync](#maperrasync)
+    - [inspect](#inspect)
+    - [inspectAsync](#inspectasync)
+    - [inspectErr](#inspecterr)
+    - [inspectErrAsync](#inspecterrasync)
   - [Additional Methods](#additional-methods)
     - [equal](#equal)
 - [Helpers for Resultifying](#helpers-for-resultifying)
@@ -341,7 +345,7 @@ This function can be used to compose the results of two functions.
 Examples:
 
 ```ts
-import { Ok, type Result } from 'rustlike-result';
+import { Ok } from 'rustlike-result';
 
 const x = await Ok<string, string>('foo').mapAsync((value) => Promise.resolve(value.length));
 assert(x.ok() === 3);
@@ -447,12 +451,82 @@ This function can be used to pass through a successful result while handling an
 Examples:
 
 ```ts
-import { Err, type Result } from 'rustlike-result';
+import { Err } from 'rustlike-result';
 
 const x = await Err(new Error('Some error message')).mapErrAsync((err) => Promise.resolve(err.message));
 assert(x.err() === 'Some error message');
 ```
 
+#### `inspect`
+
+Calls the provided closure with a reference to the contained value if `Ok`.
+
+Examples:
+
+```ts
+import { resultify } from 'rustlike-result';
+
+const num = resultify
+    .sync<SyntaxError>()(JSON.parse)('4')
+    .inspect((value: number) => console.log(`original: ${value}`))
+    .map((value) => value ** 3)
+    .expect('failed to parse number');
+assert(num === 64);
+```
+
+#### `inspectAsync`
+
+Asynchronously calls the provided closure with a reference to the contained value if `Ok`.
+
+Examples:
+
+```ts
+import { resultify } from 'rustlike-result';
+
+const num = await resultify
+    .sync<SyntaxError>()(JSON.parse)('4')
+    .inspectAsync((value: number) => {
+        console.log(`original: ${value}`);
+        return Promise.resolve();
+    })
+    .then((result) => result.map((value) => value ** 3))
+    .then((result) => result.expect('failed to parse number'));
+assert(num === 64);
+```
+
+#### `inspectErr`
+
+Calls the provided closure with a reference to the contained value if `Err`.
+
+Examples:
+
+```ts
+import { resultify } from 'rustlike-result';
+
+const num = resultify
+    .sync<SyntaxError>()(JSON.parse)('asdf')
+    .inspectErr((err) => console.log(`failed to parse json string: ${err.message}`));
+assert(num.err() instanceof SyntaxError);
+```
+
+#### `inspectErrAsync`
+
+Asynchronously calls the provided closure with a reference to the contained value if `Err`.
+
+Examples:
+
+```ts
+import { resultify } from 'rustlike-result';
+
+const num = await resultify
+    .sync<SyntaxError>()(JSON.parse)('asdf')
+    .inspectErrAsync((err) => {
+        console.log(`failed to parse json string: ${err.message}`);
+        return Promise.resolve();
+    });
+assert(num.err() instanceof SyntaxError);
+```
+
 ### Additional Methods
 #### equal
 

diff --git a/src/__tests__/result.test.ts b/src/__tests__/result.test.ts
@@ -3,6 +3,7 @@ import assert from 'node:assert';
 
 import { Err, Ok } from '../factory';
 import { RustlikeResult } from '../result';
+import { resultify } from '../resultify';
 import type { Result } from '../types';
 
 function panicFn1(): never {
@@ -761,6 +762,21 @@ describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.protot
     it('should panic if fn panic', () => {
         expect(() => Ok(1).inspect(panicFn1)).toThrow(Error('error'));
     });
+
+    it('should have correct examples doc', () => {
+        jest.spyOn(console, 'log').mockImplementationOnce(() => {});
+
+        function examples() {
+            const num = resultify
+                .sync<SyntaxError>()(JSON.parse)('4')
+                .inspect((value: number) => console.log(`original: ${value}`))
+                .map((value) => value ** 3)
+                .expect('failed to parse number');
+            assert(num === 64);
+        }
+
+        expect(examples).not.toThrow();
+    });
 });
 
 describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.prototype.inspectAsync.name}\``, () => {
@@ -809,6 +825,24 @@ describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.protot
         await expect(() => Ok(1).inspectAsync(panicFn1)).rejects.toThrow(Error('error'));
         await expect(() => Ok(1).inspectAsync(panicFn2)).rejects.toThrow(Error('error'));
     });
+
+    it('should have correct examples doc', async () => {
+        async function examples() {
+            jest.spyOn(console, 'log').mockImplementationOnce(() => {});
+
+            const num = await resultify
+                .sync<SyntaxError>()(JSON.parse)('4')
+                .inspectAsync((value: number) => {
+                    console.log(`original: ${value}`);
+                    return Promise.resolve();
+                })
+                .then((result) => result.map((value) => value ** 3))
+                .then((result) => result.expect('failed to parse number'));
+            assert(num === 64);
+        }
+
+        await expect(examples()).resolves.not.toThrow();
+    });
 });
 
 describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.prototype.inspectErr.name}\``, () => {
@@ -841,6 +875,19 @@ describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.protot
     it('should panic if fn panic', () => {
         expect(() => Err('err').inspectErr(panicFn1)).toThrow(Error('error'));
     });
+
+    it('should have correct examples doc', () => {
+        jest.spyOn(console, 'log').mockImplementationOnce(() => {});
+
+        function examples() {
+            const num = resultify
+                .sync<SyntaxError>()(JSON.parse)('asdf')
+                .inspectErr((err) => console.log(`failed to parse json string: ${err.message}`));
+            assert(num.err() instanceof SyntaxError);
+        }
+
+        expect(examples).not.toThrow();
+    });
 });
 
 describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.prototype.inspectErrAsync.name}\``, () => {
@@ -889,6 +936,22 @@ describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.protot
         await expect(() => Err('err').inspectErrAsync(panicFn1)).rejects.toThrow(Error('error'));
         await expect(() => Err('err').inspectErrAsync(panicFn2)).rejects.toThrow(Error('error'));
     });
+
+    it('should have correct examples doc', async () => {
+        jest.spyOn(console, 'log').mockImplementationOnce(() => {});
+
+        async function examples() {
+            const num = await resultify
+                .sync<SyntaxError>()(JSON.parse)('asdf')
+                .inspectErrAsync((err) => {
+                    console.log(`failed to parse json string: ${err.message}`);
+                    return Promise.resolve();
+                });
+            assert(num.err() instanceof SyntaxError);
+        }
+
+        await expect(examples()).resolves.not.toThrow();
+    });
 });
 
 describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.prototype.expect.name}\``, () => {

diff --git a/src/result.ts b/src/result.ts
@@ -259,7 +259,7 @@ export class RustlikeResult<T, E> implements Result<T, E> {
      * Examples:
      *
      * ```
-     * import { Ok, type Result } from 'rustlike-result';
+     * import { Ok } from 'rustlike-result';
      *
      * const x = await Ok<string, string>('foo').mapAsync((value) => Promise.resolve(value.length));
      * assert(x.ok() === 3);
@@ -404,7 +404,7 @@ export class RustlikeResult<T, E> implements Result<T, E> {
      * Examples:
      *
      * ```
-     * import { Err, type Result } from 'rustlike-result';
+     * import { Err } from 'rustlike-result';
      *
      * const x = await Err(new Error('Some error message')).mapErrAsync((err) => Promise.resolve(err.message));
      * assert(x.err() === 'Some error message');
@@ -419,6 +419,19 @@ export class RustlikeResult<T, E> implements Result<T, E> {
     /**
      * Calls the provided closure with a reference to the contained value if `Ok`.
      *
+     * Examples:
+     *
+     * ```
+     * import { resultify } from 'rustlike-result';
+     *
+     * const num = resultify
+     *     .sync<SyntaxError>()(JSON.parse)('4')
+     *     .inspect((value: number) => console.log(`original: ${value}`))
+     *     .map((value) => value ** 3)
+     *     .expect('failed to parse number');
+     * assert(num === 64);
+     * ```
+     *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.inspect
      */
     inspect(fn: (value: T) => void): this {
@@ -431,6 +444,22 @@ export class RustlikeResult<T, E> implements Result<T, E> {
     /**
      * Asynchronously calls the provided closure with a reference to the contained value if `Ok`.
      *
+     * Examples:
+     *
+     * ```
+     * import { resultify } from 'rustlike-result';
+     *
+     * const num = await resultify
+     *     .sync<SyntaxError>()(JSON.parse)('4')
+     *     .inspectAsync((value: number) => {
+     *         console.log(`original: ${value}`);
+     *         return Promise.resolve();
+     *     })
+     *     .then((result) => result.map((value) => value ** 3))
+     *     .then((result) => result.expect('failed to parse number'));
+     * assert(num === 64);
+     * ```
+     *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.inspect
      */
     async inspectAsync(fn: (value: T) => void | Promise<void>): Promise<this> {
@@ -443,6 +472,17 @@ export class RustlikeResult<T, E> implements Result<T, E> {
     /**
      * Calls the provided closure with a reference to the contained value if `Err`.
      *
+     * Examples:
+     *
+     * ```
+     * import { resultify } from 'rustlike-result';
+     *
+     * const num = resultify
+     *     .sync<SyntaxError>()(JSON.parse)('asdf')
+     *     .inspectErr((err) => console.log(`failed to parse json string: ${err.message}`));
+     * assert(num.err() instanceof SyntaxError);
+     * ```
+     *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.inspect_err
      */
     inspectErr(fn: (err: E) => void): this {
@@ -455,6 +495,20 @@ export class RustlikeResult<T, E> implements Result<T, E> {
     /**
      * Asynchronously calls the provided closure with a reference to the contained value if `Err`.
      *
+     * Examples:
+     *
+     * ```
+     * import { resultify } from 'rustlike-result';
+     *
+     * const num = await resultify
+     *     .sync<SyntaxError>()(JSON.parse)('asdf')
+     *     .inspectErrAsync((err) => {
+     *         console.log(`failed to parse json string: ${err.message}`);
+     *         return Promise.resolve();
+     *     });
+     * assert(num.err() instanceof SyntaxError);
+     * ```
+     *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.inspect_err
      */
     async inspectErrAsync(fn: (err: E) => void | Promise<void>): Promise<this> {