Dir structure

docs/components/Shell/SideNav.js

@@ -15,7 +15,6 @@ const items = [
     links: [
       { href: '/docs/assertions', children: 'Assertions' },
       { href: '/docs/checks', children: 'Checks' },
-      { href: '/docs/errors', children: 'Errors' },
       { href: '/docs/guards', children: 'Guards' },
       { href: '/docs/opaques', children: 'Opaques' },
       { href: '/docs/utils', children: 'Utils' },

docs/pages/docs/opaques.md

@@ -35,7 +35,7 @@ type ThingThree = Opaque<string, 'ThingTwo'>;
 // 🚨 Non-unique `Token` parameter
 ```
 
-As a side note, you can (and should) use recursive types for your opaque types to make them stronger and hopefully easier to type.
+You can, and should, use recursive types for your opaque types to make them stronger and hopefully easier to type.
 
 ```ts
 type Person = {
@@ -66,28 +66,46 @@ A generic helper function that takes a primitive value, and returns the value af
 function toOpaque<OpaqueType>(value: bigint | number | string | symbol): OpaqueType;
 ```
 
-Must be used in combination with the `Opaque` [generic type](#opaque).
+Opaque types cannot be assigned to variables with standard type declarations—this is by design, ensuring that opaquely typed values flow through the program without degrading.
+
+```ts
+const value: AccountNumber = 123;
+//    ~~~~~
+//    Type 'number' is not assignable to type 'AccountNumber'.
+```
+
+Instead use `toOpaque` to create values of opaque types.
 
 ```ts
-type NumericThing = Opaque<number, 'NumericThing'>;
+type AccountNumber = Opaque<number, 'AccountNumber'>;
 
 const value = 123;
 // → 'value' is 'number'
-const opaqueValue = toOpaque<NumericThing>(value);
-// → 'opaqueValue' is 'NumericThing'
+const opaqueValue = toOpaque<AccountNumber>(value);
+// → 'opaqueValue' is 'AccountNumber'
+```
+
+Ideally, each opaque type would have a companion function for managing their creation.
+
+```ts
+export type AccountNumber = Opaque<number, 'AccountNumber'>;
+
+export function createAccountNumber(value: number) {
+  return toOpaque<AccountNumber>(value);
+}
 ```
 
-Ensures basic type safety before casting.
+Ensures basic type safety before casting to avoid invalid primitive assignment.
 
 ```ts
-const thingTwo = toOpaque<NumericThing>('123');
-//                                      ~~~~~
-//                                      Argument of type 'string' is not assignable to parameter of type 'number'.
+const value = toOpaque<AccountNumber>('123');
+//                                    ~~~~~
+//                                    Argument of type 'string' is not assignable to parameter of type 'number'.
 ```
 
 ### toTransparent
 
-A generic helper function that takes an opaquely typed value, and returns the value after widening it to the primitive transparent type.
+A generic helper function that takes an opaquely typed value, and returns the value after widening it to the transparent primitive type.
 
 ```ts
 function toTransparent<OpaqueType>(value: OpaqueType): bigint | number | string | symbol;

docs/pages/docs/utils.md

@@ -7,9 +7,65 @@ description: Utility functions for overiding TypeScript's default behaviour
 
 Utility functions for overiding TypeScript's default behaviour
 
+## Errors
+
+Utilities for managing [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) objects.
+
+### getErrorMessage
+
+Simplifies error handling in `try...catch` statements.
+
+```ts
+function getErrorMessage(error: unknown, fallbackMessage? string): string
+```
+
+JavaScript is weird, you can `throw` anything—seriously, [anything of any type](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/throw).
+
+```ts
+try {
+  someFunctionThatMightThrow();
+} catch (error) {
+  Monitor.reportError(error.message);
+  //                  ~~~~~
+  //                  Object is of type 'unknown'.
+}
+```
+
+#### Type casting
+
+Since it's possible for library authors to throw something unexpected, we have to take precautions. Using `getErrorMessage` takes care of type casting for you, and makes error handling safe and simple.
+
+```ts
+Monitor.reportError(getErrorMessage(error));
+// 🎉 No more TypeScript issues!
+```
+
+Handles cases where the value isn't an actual `Error` object.
+
+```ts
+getErrorMessage({ message: 'Object text', other: () => 'Properties' });
+// → 'Object text'
+```
+
+Supports a fallback message for "falsy" values.
+
+```ts
+getErrorMessage(undefined);
+// → 'Unknown error'
+getErrorMessage(undefined, 'Custom message text');
+// → 'Custom message text'
+```
+
+Fails gracefully by stringifying unexpected values.
+
+```ts
+getErrorMessage({ msg: 'Something went wrong' });
+// → '{ "msg": "Something went wrong" }'
+```
+
 ## Objects
 
-Utility functions for objects.
+Utility functions for [objects](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object).
 
 ### typedEntries
 
@@ -59,4 +115,9 @@ const thing = Object.keys(obj).map(key => {
   //     Element implicitly has an 'any' type because expression of type 'string' can't be used to index type '{ foo: number; bar: number; }'.
   //       No index signature with a parameter of type 'string' was found on type '{ foo: number; bar: number; }'.
 });
+
+const thing2 = typedKeys(obj).map(key => {
+  return obj[key];
+  // 🎉 No more TypeScript issues!
+});
 ```

src/assertions.test.ts

@@ -1,5 +1,5 @@
 import { assert, assertNever } from './assertions';
-import { getErrorMessage } from './errors';
+import { getErrorMessage } from './utils/error';
 
 describe('assertions', () => {
   describe('assert', () => {