ts-error-as-value - npm Package Compare versions

Comparing version 0.0.1 to 0.0.2

lib/globals.js

@@ -5,8 +5,8 @@ "use strict";
 if (typeof window !== "undefined" || process.browser) {
+    window.ok = _1.ok;
+    window.err = _1.err;
+}
+else {
     globalThis.ok = _1.ok;
     globalThis.err = _1.err;
 }
-else {
-    window.ok = _1.ok;
-    window.err = _1.err;
-}

package.json

 {
   "name": "ts-error-as-value",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "",
@@ -5,0 +5,0 @@ "main": "lib/index.ts",

README.md

@@ -6,6 +6,122 @@ ### Typescript error as value
 
-#### Set types and functions to globals
+### Install
+
+```bash
+yarn install ts-error-as-value
+```
+---
+
+### (Optionally) Make functions and types global
 ```ts
 import "ts-error-as-value/lib/globals";
 ```
-This will make the functions ok and err, as well as the types Ok, Err and Result globally available.
+This will make the functions ok and err, as well as the types Ok, Err and Result globally available
+
+---
+
+### Result type
+
+```typescript
+type None = null;
+
+type Err<T, E extends Error = Error> = {
+  data: never,
+  error: E,
+  get errorStack(): Error[],
+  unwrap(): void, // Returns the value, but throws an error if the result is an Error
+  unwrapOr<D>(defaultValue: D): D, // Returns the value or gives you a default value if it's an error
+  mapErr<E2 extends Error>(fn: (err: E) => E2): Err<T, E2>, // If the result is an error, map the error to another error
+  andThen<N>(fn: (data: never) => N): Err<T, E> // If the result is not an error, map the data in it
+};
+
+type Ok<T> = {
+  data: T,
+  error: never,
+  get errorStack(): never,
+  unwrap(): T, // Returns the value, but throws an error if the result is an Error
+  unwrapOr<D>(defaultValue: D): T, // Returns the value or gives you a default value if it's an error
+  mapErr<E2 extends Error>(fn: (err: never) => E2): Ok<T>, // If the result is an error, map the error to another error
+  andThen<N>(fn: (data: T) => N): Ok<N> // If the result is not an error, map the data in it
+};
+
+type Result<
+  T, E extends Error = ErrorResult
+> = Err<T, E> | Ok<T>;
+```
+
+---
+
+### Functions
+```ts
+const err: <E extends Error>(error: E) => Err<None>;
+const ok: <T>(data: T) => Ok<T>;
+```
+
+---
+
+### Basic Usage
+*Wrap the returns from functions with err for errors, and ok for non-error returns so that the function calling it receives a Result type.*
+
+```ts
+const fnWithResult = (): Result<string, Error> => {
+  if ("" !== "") {
+    return ok("hello");
+  }
+  return err(new Error("Method failed"));
+};
+
+const { data, error } = fnWithResult();
+
+if (error) {
+  // is an error
+} else {
+  // guaranteed to not be an error, and typescript knows this
+}
+```
+
+---
+
+Or with promises:
+
+```ts
+const fnWithResult = async (): Promise<Result<string, Error>> => {
+  if ("" !== "") {
+    return ok("hello");
+  }
+  return err(new Error("Method failed"));
+};
+
+const callsFnThatCallsFnWithResult = async () => {
+  const { data, error, errorStack } = (await fnWithResult())
+  if (error) {
+    return err(error);
+  }
+  return ok(data);
+};
+
+callsFnThatCallsFnWithResult();
+```
+
+--- 
+
+### Methods on Result
+```ts
+
+class NewError extends Error {}
+
+const fnWithResult = (): Result<string, Error> => {
+  if ("" !== "") {
+    return ok("hello");
+  }
+  return err(new Error("Method failed"));
+};
+
+const { data, error } = fnWithResult()
+    .mapErr(error => new NewError("Failed to call fnWithResult"))
+    .andThen(data => {
+      return data === "hello";
+    });
+```
+Because of using andThen, data will be boolean if fnWithResult returns a value.
+
+Because of mapErr, error will be an instance of NewError if fnWithResult returns an error

src/index.ts

@@ -5,3 +5,2 @@ import { ErrorResult, isErrorResult } from "./error-result";
 
-
 export type Err<T, E extends Error = Error> = {
@@ -11,6 +10,6 @@ data: never,
   get errorStack(): Error[],
-  unwrap(): void,
-  unwrapOr<D>(defaultValue: D): D,
-  mapErr<E2 extends Error>(fn: (err: E) => E2): Err<T, E2>,
-  andThen<N>(fn: (data: never) => N): Err<T, E>
+  unwrap(): void, // Returns the value, but throws an error if the result is an Error
+  unwrapOr<D>(defaultValue: D): D, // Returns the value or gives you a default value if it's an error
+  mapErr<E2 extends Error>(fn: (err: E) => E2): Err<T, E2>, // If the result is an error, map the error to another error
+  andThen<N>(fn: (data: never) => N): Err<T, E> // If the result is not an error, map the data in it
 };
@@ -22,6 +21,6 @@
   get errorStack(): never,
-  unwrap(): T,
-  unwrapOr<D>(defaultValue: D): T,
-  mapErr<E2 extends Error>(fn: (err: never) => E2): Ok<T>,
-  andThen<N>(fn: (data: T) => N): Ok<N>
+  unwrap(): T, // Returns the value, but throws an error if the result is an Error
+  unwrapOr<D>(defaultValue: D): T, // Returns the value or gives you a default value if it's an error
+  mapErr<E2 extends Error>(fn: (err: never) => E2): Ok<T>, // If the result is an error, map the error to another error
+  andThen<N>(fn: (data: T) => N): Ok<N> // If the result is not an error, map the data in it
 };
@@ -46,4 +45,4 @@
       },
-      mapErr<E2 extends Error>(fn: (err: E) => E2): Err<null, E2> {
-        return err(ErrorResult.new$$$(error, fn(error))) as Err<null, E2>;
+      mapErr<E2 extends Error>(fn: (err: E) => E2): Err<None, E2> {
+        return err(ErrorResult.new$$$(error, fn(error))) as Err<None, E2>;
       },
@@ -68,4 +67,4 @@ unwrapOr<D>(defaultValue: D): D {
     },
-    mapErr<E2 extends Error>(fn: (err: E) => E2): Err<null, E2> {
-      return err(ErrorResult.new$$$(error, fn(error))) as Err<null, E2>;
+    mapErr<E2 extends Error>(fn: (err: E) => E2): Err<None, E2> {
+      return err(ErrorResult.new$$$(error, fn(error))) as Err<None, E2>;
     },
@@ -72,0 +71,0 @@ unwrapOr<D>(defaultValue: D): D {

No alert changes

Improved metrics

Total package byte prevSize

31629

increased by4.04%

Number of lines in readme file

126

increased by1045.45%

Worsened metrics

Number of package files

27

decreased by-10%

No dependency changes