defekt - npm Package Compare versions

Comparing version 9.1.1 to 9.2.0

build/lib/index.d.ts

 import { CustomError } from './CustomError';
 import { CustomErrorConstructor } from './CustomErrorConstructor';
 import { defekt } from './defekt';
+import { ensureUnknownIsError } from './ensureUnknownIsError';
 import { hydrateResult } from './hydrateResult';
@@ -10,3 +11,3 @@ import { isCustomError } from './isCustomError';
 import { hydrateCustomError, HydratingErrorFailed } from './hydrateCustomError';
-export { CustomError, defekt, error, hydrateCustomError, HydratingErrorFailed, hydrateResult, isCustomError, isError, isResult, ResultDoesNotContainError, value };
+export { CustomError, defekt, ensureUnknownIsError, error, hydrateCustomError, HydratingErrorFailed, hydrateResult, isCustomError, isError, isResult, ResultDoesNotContainError, value };
 export type { CustomErrorConstructor, Result };

build/lib/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.value = exports.ResultDoesNotContainError = exports.isResult = exports.isError = exports.isCustomError = exports.hydrateResult = exports.HydratingErrorFailed = exports.hydrateCustomError = exports.error = exports.defekt = exports.CustomError = void 0;
+exports.value = exports.ResultDoesNotContainError = exports.isResult = exports.isError = exports.isCustomError = exports.hydrateResult = exports.HydratingErrorFailed = exports.hydrateCustomError = exports.error = exports.ensureUnknownIsError = exports.defekt = exports.CustomError = void 0;
 const CustomError_1 = require("./CustomError");
@@ -8,2 +8,4 @@ Object.defineProperty(exports, "CustomError", { enumerable: true, get: function () { return CustomError_1.CustomError; } });
 Object.defineProperty(exports, "defekt", { enumerable: true, get: function () { return defekt_1.defekt; } });
+const ensureUnknownIsError_1 = require("./ensureUnknownIsError");
+Object.defineProperty(exports, "ensureUnknownIsError", { enumerable: true, get: function () { return ensureUnknownIsError_1.ensureUnknownIsError; } });
 const hydrateResult_1 = require("./hydrateResult");
@@ -10,0 +12,0 @@ Object.defineProperty(exports, "hydrateResult", { enumerable: true, get: function () { return hydrateResult_1.hydrateResult; } });

CHANGELOG.md

@@ -0,1 +1,8 @@
+# [9.2.0](https://github.com/thenativeweb/defekt/compare/9.1.1...9.2.0) (2022-06-01)
+
+
+### Features
+
+* Implement ensureUnknownIsError and extend readme. ([#363](https://github.com/thenativeweb/defekt/issues/363)) ([0abf81d](https://github.com/thenativeweb/defekt/commit/0abf81da1067b68f2d5f90029f1180aebbfbf4eb))
+
 ## [9.1.1](https://github.com/thenativeweb/defekt/compare/9.1.0...9.1.1) (2022-03-25)
@@ -2,0 +9,0 @@

lib/index.ts

 import { CustomError } from './CustomError';
 import { CustomErrorConstructor } from './CustomErrorConstructor';
 import { defekt } from './defekt';
+import { ensureUnknownIsError } from './ensureUnknownIsError';
 import { hydrateResult } from './hydrateResult';
@@ -14,2 +15,3 @@ import { isCustomError } from './isCustomError';
   defekt,
+  ensureUnknownIsError,
   error,
@@ -16,0 +18,0 @@ hydrateCustomError,

package.json

 {
   "name": "defekt",
-  "version": "9.1.1",
+  "version": "9.2.0",
   "description": "defekt is custom errors made simple.",
@@ -36,4 +36,4 @@ "contributors": [
   "devDependencies": {
-    "assertthat": "6.5.1",
-    "roboter": "13.0.0",
+    "assertthat": "6.5.2",
+    "roboter": "13.1.0",
     "semantic-release-configuration": "2.0.7"
@@ -40,0 +40,0 @@ },

README.md

@@ -322,9 +322,9 @@ # defekt
 if (hydrationResult.hasError()) {
-    // The hydration has failed.
+  // The hydration has failed.
 } else {
-    const result = hydrationResult.value;
-    
-    if (result.hasError()) {
-        // Continue with your normal error handling.
-    }
+  const result = hydrationResult.value;
+
+  if (result.hasError()) {
+    // Continue with your normal error handling.
+  }
 }
@@ -335,2 +335,71 @@ ```
 
+## Using the various utilities
+
+### Recognizing errors with `isError`
+
+The function `isError` is used to recognize anything that is derived from the built-in `Error` class. It relies solely on the prototype chain. Use it for example in a `catch` clause when trying to determine, wether what you have caught is actually an error:
+
+```typescript
+import { isError } from 'defekt';
+
+try {
+  // ...
+} catch (ex: unknown) {
+  if (isError(ex)) {
+    // You can now access ex.message, ex.stack, ...
+  }
+}
+```
+
+### Recognizing custom errors with `isCustomError`
+
+In addition to recognizing things that are derived from `Error`, `isCustomError` recognizes things that are derived from `CustomError` and even lets you identify specific error types.
+
+You can either identify a general `CustomError`:
+
+```typescript
+import { isCustomError } from 'defekt';
+
+try {
+  // ...
+} catch (ex: unknown) {
+  if (isCustomError(ex)) {
+    // You can now access ex.message, ex.stack, ..., but also ex.code.
+  }
+}
+```
+
+Or you can pass a `CustomError` constructor to make sure you have a specific type of error in hand:
+
+```typescript
+import { defekt, isCustomError } from 'defekt';
+
+class MyCustomError extends defekt({ code: 'MyCustomError' }) {}
+
+try {
+  // ...
+} catch (ex: unknown) {
+  if (isCustomError(ex, MyCustomError)) {
+    // In this block ex is of type `MyCustomError`.
+  }
+}
+```
+
+### Making sure something is an error or wrapping it, if not, using `ensureUnknownIsError`
+
+One of the greatest regrets of JavaScript is the ability to throw anything. If you want to bullet-proof your error handling, you need to check that what you catch in a `catch` clause is actually an `Error`. `ensureUnknownIsError` takes something you caught and wraps it in an `Error` if necessary. If the caught thing already is an `Error`, `ensureUnknownIsError` returns it unchanged.
+
+```typescript
+import {ensureUnknownIsError} from "./ensureUnknownIsError";
+
+try {
+  // ...
+} catch (ex: unknown) {
+  const error = ensureUnknownIsError({ error: ex });
+
+  // Now you can go on with your usual error handling and rest assured, that
+  // `error` is actually an `Error`.
+}
+```
+
 ## Running quality assurance
@@ -337,0 +406,0 @@

No alert changes

Improved metrics

Total package byte prevSize

55673

increased by7.76%

Number of package files

45

increased by7.14%

Lines of code

765

increased by6.4%

Number of lines in readme file

410

increased by20.23%

No dependency changes