feat: add examples for isErr, isErrAnd, isErrAndAsync

yifanwww · Mar 23, 2024 · a22fefd · a22fefd
1 parent 625b9ed
commit a22fefd
Show file tree

Hide file tree

Showing 4 changed files with 219 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -197,13 +197,77 @@ Examples:
 import { Err, Ok, type Result } from 'rustlike-result';
 
 const x: Result<number, string> = Ok(2);
-assert(await x.isOkAndAsync((value) => Promise.resolve(value > 1)) === true);
+assert((await x.isOkAndAsync((value) => Promise.resolve(value > 1))) === true);
 
 const y: Result<number, string> = Ok(0);
-assert(await y.isOkAndAsync((value) => Promise.resolve(value > 1)) === false);
+assert((await y.isOkAndAsync((value) => Promise.resolve(value > 1))) === false);
 
 const z: Result<number, string> = Err('Some error message');
-assert(await z.isOkAndAsync((value) => Promise.resolve(value > 1)) === false);
+assert((await z.isOkAndAsync((value) => Promise.resolve(value > 1))) === false);
+```
+
+#### `isErr`
+
+Returns `true` if the result is `Err`.
+
+Examples:
+
+```ts
+import { Err, Ok, type Result } from 'rustlike-result';
+
+const x: Result<number, string> = Ok(-3);
+assert(x.isErr() === false);
+
+const y: Result<number, string> = Err('Some error message');
+assert(y.isErr() === true);
+```
+
+#### `isErrAnd`
+
+Returns `true` if the result is `Err` and the value inside of it matches a predicate.
+
+Examples:
+
+```ts
+import { Err, Ok, type Result } from 'rustlike-result';
+
+enum ErrorKind {
+NOT_FOUND,
+PERMISSION_DENIED,
+}
+
+const x: Result<number, ErrorKind> = Err(ErrorKind.NOT_FOUND);
+assert(x.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === true);
+
+const y: Result<number, ErrorKind> = Err(ErrorKind.PERMISSION_DENIED);
+assert(y.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === false);
+
+const z: Result<number, ErrorKind> = Ok(123);
+assert(z.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === false);
+```
+
+#### `isErrAndAsync`
+
+Asynchronously returns `true` if the result is `Err` and the value inside of it matches a predicate.
+
+Examples:
+
+```ts
+import { Err, Ok, type Result } from 'rustlike-result';
+
+enum ErrorKind {
+NOT_FOUND,
+PERMISSION_DENIED,
+}
+
+const x: Result<number, ErrorKind> = Err(ErrorKind.NOT_FOUND);
+assert((await x.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === true);
+
+const y: Result<number, ErrorKind> = Err(ErrorKind.PERMISSION_DENIED);
+assert((await y.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === false);
+
+const z: Result<number, ErrorKind> = Ok(123);
+assert((await z.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === false);
 ```
 
 ### Additional Methods

diff --git a/src/__tests__/result.test.ts b/src/__tests__/result.test.ts
@@ -151,6 +151,18 @@ describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.protot
         expect(Ok(1).isErr()).toBe(false);
         expect(Err('Some error message').isErr()).toBe(true);
     });
+
+    it('should have correct examples doc', () => {
+        function examples() {
+            const x: Result<number, string> = Ok(-3);
+            assert(x.isErr() === false);
+
+            const y: Result<number, string> = Err('Some error message');
+            assert(y.isErr() === true);
+        }
+
+        expect(examples).not.toThrow();
+    });
 });
 
 describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.prototype.isErrAnd.name}\``, () => {
@@ -185,6 +197,21 @@ describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.protot
     it('should panic if fn panic', () => {
         expect(() => Err(ErrorKind.NOT_FOUND).isErrAnd(panicFn1)).toThrow(Error('error'));
     });
+
+    it('should have correct examples doc', () => {
+        function examples() {
+            const x: Result<number, ErrorKind> = Err(ErrorKind.NOT_FOUND);
+            assert(x.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === true);
+
+            const y: Result<number, ErrorKind> = Err(ErrorKind.PERMISSION_DENIED);
+            assert(y.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === false);
+
+            const z: Result<number, ErrorKind> = Ok(123);
+            assert(z.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === false);
+        }
+
+        expect(examples).not.toThrow();
+    });
 });
 
 describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.prototype.isErrAndAsync.name}\``, () => {
@@ -233,6 +260,21 @@ describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.protot
         await expect(() => Err(ErrorKind.NOT_FOUND).isErrAndAsync(panicFn1)).rejects.toThrow(Error('error'));
         await expect(() => Err(ErrorKind.NOT_FOUND).isErrAndAsync(panicFn2)).rejects.toThrow(Error('error'));
     });
+
+    it('should have correct examples doc', async () => {
+        async function examples() {
+            const x: Result<number, ErrorKind> = Err(ErrorKind.NOT_FOUND);
+            assert((await x.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === true);
+
+            const y: Result<number, ErrorKind> = Err(ErrorKind.PERMISSION_DENIED);
+            assert((await y.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === false);
+
+            const z: Result<number, ErrorKind> = Ok(123);
+            assert((await z.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === false);
+        }
+
+        await expect(examples()).resolves.not.toThrow();
+    });
 });
 
 describe(`Test method \`${RustlikeResult.name}.prototype.${RustlikeResult.prototype.ok.name}\``, () => {

diff --git a/src/result.ts b/src/result.ts
@@ -93,13 +93,13 @@ export class RustlikeResult<T, E> implements Result<T, E> {
      * import { Err, Ok, type Result } from 'rustlike-result';
      *
      * const x: Result<number, string> = Ok(2);
-     * assert(await x.isOkAndAsync((value) => Promise.resolve(value > 1)) === true);
+     * assert((await x.isOkAndAsync((value) => Promise.resolve(value > 1))) === true);
      *
      * const y: Result<number, string> = Ok(0);
-     * assert(await y.isOkAndAsync((value) => Promise.resolve(value > 1)) === false);
+     * assert((await y.isOkAndAsync((value) => Promise.resolve(value > 1))) === false);
      *
      * const z: Result<number, string> = Err('Some error message');
-     * assert(await z.isOkAndAsync((value) => Promise.resolve(value > 1)) === false);
+     * assert((await z.isOkAndAsync((value) => Promise.resolve(value > 1))) === false);
      * ```
      *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.is_ok_and
@@ -111,6 +111,18 @@ export class RustlikeResult<T, E> implements Result<T, E> {
     /**
      * Returns `true` if the result is `Err`.
      *
+     * Examples:
+     *
+     * ```
+     * import { Err, Ok, type Result } from 'rustlike-result';
+     *
+     * const x: Result<number, string> = Ok(-3);
+     * assert(x.isErr() === false);
+     *
+     * const y: Result<number, string> = Err('Some error message');
+     * assert(y.isErr() === true);
+     * ```
+     *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.is_err
      */
     isErr(): boolean {
@@ -120,6 +132,26 @@ export class RustlikeResult<T, E> implements Result<T, E> {
     /**
      * Returns `true` if the result is `Err` and the value inside of it matches a predicate.
      *
+     * Examples:
+     *
+     * ```
+     * import { Err, Ok, type Result } from 'rustlike-result';
+     *
+     * enum ErrorKind {
+     *   NOT_FOUND,
+     *   PERMISSION_DENIED,
+     * }
+     *
+     * const x: Result<number, ErrorKind> = Err(ErrorKind.NOT_FOUND);
+     * assert(x.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === true);
+     *
+     * const y: Result<number, ErrorKind> = Err(ErrorKind.PERMISSION_DENIED);
+     * assert(y.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === false);
+     *
+     * const z: Result<number, ErrorKind> = Ok(123);
+     * assert(z.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === false);
+     * ```
+     *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.is_err_and
      */
     isErrAnd(fn: (err: E) => boolean): boolean {
@@ -129,6 +161,26 @@ export class RustlikeResult<T, E> implements Result<T, E> {
     /**
      * Asynchronously returns `true` if the result is `Err` and the value inside of it matches a predicate.
      *
+     * Examples:
+     *
+     * ```
+     * import { Err, Ok, type Result } from 'rustlike-result';
+     *
+     * enum ErrorKind {
+     *   NOT_FOUND,
+     *   PERMISSION_DENIED,
+     * }
+     *
+     * const x: Result<number, ErrorKind> = Err(ErrorKind.NOT_FOUND);
+     * assert((await x.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === true);
+     *
+     * const y: Result<number, ErrorKind> = Err(ErrorKind.PERMISSION_DENIED);
+     * assert((await y.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === false);
+     *
+     * const z: Result<number, ErrorKind> = Ok(123);
+     * assert((await z.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === false);
+     * ```
+     *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.is_err_and
      */
     async isErrAndAsync(fn: (err: E) => boolean | Promise<boolean>): Promise<boolean> {

diff --git a/src/types.ts b/src/types.ts
@@ -61,13 +61,13 @@ export interface Result<T, E> {
      * import { Err, Ok, type Result } from 'rustlike-result';
      *
      * const x: Result<number, string> = Ok(2);
-     * assert(await x.isOkAndAsync((value) => Promise.resolve(value > 1)) === true);
+     * assert((await x.isOkAndAsync((value) => Promise.resolve(value > 1))) === true);
      *
      * const y: Result<number, string> = Ok(0);
-     * assert(await y.isOkAndAsync((value) => Promise.resolve(value > 1)) === false);
+     * assert((await y.isOkAndAsync((value) => Promise.resolve(value > 1))) === false);
      *
      * const z: Result<number, string> = Err('Some error message');
-     * assert(await z.isOkAndAsync((value) => Promise.resolve(value > 1)) === false);
+     * assert((await z.isOkAndAsync((value) => Promise.resolve(value > 1))) === false);
      * ```
      *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.is_ok_and
@@ -77,20 +77,72 @@ export interface Result<T, E> {
     /**
      * Returns `true` if the result is `Err`.
      *
+     * Examples:
+     *
+     * ```
+     * import { Err, Ok, type Result } from 'rustlike-result';
+     *
+     * const x: Result<number, string> = Ok(-3);
+     * assert(x.isErr() === false);
+     *
+     * const y: Result<number, string> = Err('Some error message');
+     * assert(y.isErr() === true);
+     * ```
+     *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.is_err
      */
     isErr(): boolean;
 
     /**
      * Returns `true` if the result is `Err` and the value inside of it matches a predicate.
      *
+     * Examples:
+     *
+     * ```
+     * import { Err, Ok, type Result } from 'rustlike-result';
+     *
+     * enum ErrorKind {
+     *   NOT_FOUND,
+     *   PERMISSION_DENIED,
+     * }
+     *
+     * const x: Result<number, ErrorKind> = Err(ErrorKind.NOT_FOUND);
+     * assert(x.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === true);
+     *
+     * const y: Result<number, ErrorKind> = Err(ErrorKind.PERMISSION_DENIED);
+     * assert(y.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === false);
+     *
+     * const z: Result<number, ErrorKind> = Ok(123);
+     * assert(z.isErrAnd((value) => value === ErrorKind.NOT_FOUND) === false);
+     * ```
+     *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.is_err_and
      */
     isErrAnd(fn: (err: E) => boolean): boolean;
 
     /**
      * Asynchronously returns `true` if the result is `Err` and the value inside of it matches a predicate.
      *
+     * Examples:
+     *
+     * ```
+     * import { Err, Ok, type Result } from 'rustlike-result';
+     *
+     * enum ErrorKind {
+     *   NOT_FOUND,
+     *   PERMISSION_DENIED,
+     * }
+     *
+     * const x: Result<number, ErrorKind> = Err(ErrorKind.NOT_FOUND);
+     * assert((await x.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === true);
+     *
+     * const y: Result<number, ErrorKind> = Err(ErrorKind.PERMISSION_DENIED);
+     * assert((await y.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === false);
+     *
+     * const z: Result<number, ErrorKind> = Ok(123);
+     * assert((await z.isErrAndAsync((value) => Promise.resolve(value === ErrorKind.NOT_FOUND))) === false);
+     * ```
+     *
      * ref: https://doc.rust-lang.org/std/result/enum.Result.html#method.is_err_and
      */
     isErrAndAsync(fn: (err: E) => boolean | Promise<boolean>): Promise<boolean>;