[wip] factoring vdk out into several packages

libs/vdk_rlp/src/safe.ts

@@ -0,0 +1,112 @@
+/**
+ * "Safe" error handling
+ *
+ * The idea here is that there are situations where it is known
+ *
+ * ```typescript
+ * type Safe<ok_t, err_t>
+ *     = Ok<ok_t>
+ *     | Error<err_t>;
+ *
+ * type Ok<ok_t>
+ *     = {ok     : true,
+ *        result : ok_t};
+ *
+ * type Error<err_t>
+ *     = {ok    : false,
+ *        error : err_t};
+ * ```
+ *
+ * 1. a given function call is likely to fail
+ * 2. the likely errors can be enumerated
+ *
+ * These are called "positive errors".  An example would be a page script
+ * asking a browser wallet extension to sign a transaction. The following
+ * errors, among others, are likely:
+ *
+ * - the user does not have a wallet installed
+ * - the user has a wallet but does not have the correct signing key
+ * - the user rejects the transaction
+ * - the sign request timed out
+ *
+ * These errors should not generate exceptions, as these behaviors are to some
+ * degree "expected".
+ */
+
+export {
+    Safe,
+    Ok,
+    Error,
+    ok,
+    error,
+    unsafe
+}
+
+
+/**
+ * Type that catches positive errors
+ */
+type Safe<ok_t, err_t>
+    = Ok<ok_t>
+    | Error<err_t>;
+
+
+/**
+ * Ok type
+ */
+type Ok<ok_t>
+    = {ok     : true,
+       result : ok_t};
+
+
+/**
+ * Error type
+ */
+type Error<err_t>
+    = {ok    : false,
+       error : err_t};
+
+
+/**
+ * Constructs an `Ok` value from a pure value
+ */
+function
+ok
+    <ok_t>
+    (x : ok_t)
+    : Ok<ok_t>
+{
+    return {ok: true, result: x};
+}
+
+
+
+/**
+ * Constructs an `Error` value from a pure value
+ */
+function
+error
+    <err_t>
+    (x: err_t)
+    : Error<err_t>
+{
+    return {ok: false, error: x};
+}
+
+
+
+/**
+ * Takes a `Safe` value, if `ok`, returns the `ok_t`, or if an error throws the
+ * `err_t`
+ */
+function
+unsafe
+    <ok_t, err_t>
+    (x: Safe<ok_t, err_t>)
+    : ok_t
+{
+    if (x.ok)
+        return x.result;
+    else
+        throw x.error;
+}