feat: initial version

.presetterrc.json

@@ -0,0 +1,18 @@
+{
+    "preset": "presetter-preset-strict",
+    "config": {
+        "tsconfig": {
+            "compilerOptions": {
+                "lib": [
+                    "ES2021"
+                ]
+            }
+        },
+        "prettier": {
+            "singleQuote": false
+        }
+    },
+    "variable": {
+        "source": "src"
+    }
+}

.releaserc

@@ -0,0 +1,32 @@
+{
+    "plugins": [
+        "@semantic-release/commit-analyzer",
+        "@semantic-release/release-notes-generator",
+        [
+            "@semantic-release/changelog",
+            {
+                "changelogFile": "docs/CHANGELOG.md"
+            }
+        ],
+        "@semantic-release/git",
+        {
+            "assets": [
+                "package.json",
+                "docs/CHANGELOG.md",
+                "npm-shrinkwrap.json"
+            ]
+        },
+        "@semantic-release/npm"
+    ],
+    "branches": [
+        "master",
+        {
+            name: "develop",
+            prerelease: true
+        },
+        {
+            name: "develop-*",
+            prerelease: true
+        },
+    ]
+}

LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) <year> <copyright holders>
+Copyright (c) 2023 Hammer Technologies LLC
+Copyright (c) 2022 Skynet Labs
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -1,2 +1,3 @@
 # libweb
 
+Library is based on, and copies much of its work from https://github.com/SkynetLabs/skynet-kernel/tree/beta/libs/libskynet

package.json

@@ -0,0 +1,20 @@
+{
+    "name": "@lumeweb/libweb",
+    "version": "0.1.0",
+    "devDependencies": {
+        "presetter": "^4.0.0",
+        "presetter-preset-strict": "^4.0.0",
+        "semantic-release": "^21.0.5"
+    },
+    "readme": "ERROR: No README data found!",
+    "_id": "@lumeweb/libweb@0.1.0",
+    "scripts": {
+        "prepare": "presetter bootstrap",
+        "semantic-release": "semantic-release"
+    },
+    "dependencies": {
+        "@lumeweb/libportal": "^0.1.0",
+        "@noble/curves": "^1.1.0",
+        "@noble/hashes": "^1.3.1"
+    }
+}

src/cid.ts

@@ -0,0 +1,35 @@
+import { ErrTuple } from "#types.js";
+import {
+  decodeCid as decodeCidPortal,
+  encodeCid as encodeCidPortal,
+} from "@lumeweb/libportal";
+import { addContextToErr } from "#err.js";
+
+export function encodeCid(hash: Uint8Array, size: bigint): any;
+export function encodeCid(hash: string, size: bigint): any;
+export function encodeCid(hash: any, size: bigint): ErrTuple {
+  try {
+    return [encodeCidPortal(hash, size), null];
+  } catch (e) {
+    return [null, addContextToErr(e as Error, "failed to encode cid")];
+  }
+}
+
+export function decodeCid(cid: string): ErrTuple {
+  try {
+    return [decodeCidPortal(cid), null];
+  } catch (e) {
+    return [null, addContextToErr(e as Error, "failed to decode cid")];
+  }
+}
+
+export function verifyCid(cid: string): boolean {
+  try {
+    decodeCidPortal(cid);
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+export { CID } from "@lumeweb/libportal";

src/download.ts

@@ -0,0 +1 @@
+export function downloadObject(cid: string) {}

src/encoding.ts

@@ -0,0 +1,130 @@
+import { addContextToErr } from "./err.js";
+import { Err } from "./types.js";
+
+const MAX_UINT_64 = 18446744073709551615n;
+
+// b64ToBuf will take an untrusted base64 string and convert it into a
+// Uin8Array, returning an error if the input is not valid base64.
+const b64regex = /^[0-9a-zA-Z-_/+=]*$/;
+function b64ToBuf(b64: string): [Uint8Array, Err] {
+  // Check that the final string is valid base64.
+  if (!b64regex.test(b64)) {
+    return [new Uint8Array(0), "provided string is not valid base64"];
+  }
+
+  // Swap any '-' characters for '+', and swap any '_' characters for '/'
+  // for use in the atob function.
+  b64 = b64.replaceAll("-", "+").replaceAll("_", "/");
+
+  // Perform the conversion.
+  const binStr = atob(b64);
+  const len = binStr.length;
+  const buf = new Uint8Array(len);
+  for (let i = 0; i < len; i++) {
+    buf[i] = binStr.charCodeAt(i);
+  }
+  return [buf, null];
+}
+
+// bufToHex takes a Uint8Array as input and returns the hex encoding of those
+// bytes as a string.
+function bufToHex(buf: Uint8Array): string {
+  return [...buf].map((x) => x.toString(16).padStart(2, "0")).join("");
+}
+
+// bufToB64 will convert a Uint8Array to a base64 string with URL encoding and
+// no padding characters.
+function bufToB64(buf: Uint8Array): string {
+  const b64Str = btoa(String.fromCharCode(...buf));
+  return b64Str.replaceAll("+", "-").replaceAll("/", "_").replaceAll("=", "");
+}
+
+// bufToStr takes an ArrayBuffer as input and returns a text string. bufToStr
+// will check for invalid characters.
+function bufToStr(buf: ArrayBuffer): [string, Err] {
+  try {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(buf);
+    return [text, null];
+  } catch (err: any) {
+    return [
+      "",
+      addContextToErr(err.toString(), "unable to decode ArrayBuffer to string"),
+    ];
+  }
+}
+
+// decodeU64 is the opposite of encodeU64, it takes a uint64 encoded as 8 bytes
+// and decodes them into a BigInt.
+function decodeU64(u8: Uint8Array): [bigint, Err] {
+  // Check the input.
+  if (u8.length !== 8) {
+    return [0n, "input should be 8 bytes"];
+  }
+
+  // Process the input.
+  let num = 0n;
+  for (let i = u8.length - 1; i >= 0; i--) {
+    num *= 256n;
+    num += BigInt(u8[i]);
+  }
+  return [num, null];
+}
+
+// encodeU64 will encode a bigint in the range of a uint64 to an 8 byte
+// Uint8Array.
+function encodeU64(num: bigint): [Uint8Array, Err] {
+  // Check the bounds on the bigint.
+  if (num < 0) {
+    return [new Uint8Array(0), "expected a positive integer"];
+  }
+  if (num > MAX_UINT_64) {
+    return [new Uint8Array(0), "expected a number no larger than a uint64"];
+  }
+
+  // Encode the bigint into a Uint8Array.
+  const encoded = new Uint8Array(8);
+  for (let i = 0; i < encoded.length; i++) {
+    encoded[i] = Number(num & 0xffn);
+    num = num >> 8n;
+  }
+  return [encoded, null];
+}
+
+// hexToBuf takes an untrusted string as input, verifies that the string is
+// valid hex, and then converts the string to a Uint8Array.
+const allHex = /^[0-9a-f]+$/i;
+function hexToBuf(hex: string): [Uint8Array, Err] {
+  // The rest of the code doesn't handle zero length input well, so we handle
+  // that separately. It's not an error, we just return an empty array.
+  if (hex.length === 0) {
+    return [new Uint8Array(0), null];
+  }
+
+  // Check that the length makes sense.
+  if (hex.length % 2 !== 0) {
+    return [new Uint8Array(0), "input has incorrect length"];
+  }
+
+  // Check that all of the characters are legal.
+  if (!allHex.test(hex)) {
+    return [new Uint8Array(0), "input has invalid character"];
+  }
+
+  // Create the buffer and fill it.
+  const matches = hex.match(/.{2}/g);
+  if (matches === null) {
+    return [new Uint8Array(0), "input is incomplete"];
+  }
+  const u8 = new Uint8Array(matches.map((byte) => parseInt(byte, 16)));
+  return [u8, null];
+}
+
+export {
+  b64ToBuf,
+  bufToHex,
+  bufToB64,
+  bufToStr,
+  decodeU64,
+  encodeU64,
+  hexToBuf,
+};

src/err.ts

@@ -0,0 +1,16 @@
+import { objAsString } from "./objAsString.js";
+
+// addContextToErr is a helper function that standardizes the formatting of
+// adding context to an error.
+//
+// NOTE: To protect against accidental situations where an Error type or some
+// other type is provided instead of a string, we wrap both of the inputs with
+// objAsString before returning them. This prevents runtime failures.
+function addContextToErr(err: any, context: string): string {
+  if (err === null || err === undefined) {
+    err = "[no error provided]";
+  }
+  return objAsString(context) + ": " + objAsString(err);
+}
+
+export { addContextToErr };

src/errTracker.ts

@@ -0,0 +1,101 @@
+// errTracker.ts defines an 'ErrTracker' type which keeps track of historical
+// errors. When the number of errors gets too large, it randomly starts pruning
+// errors. It always keeps 250 of the most recent errors, and then keeps up to
+// 500 historic errors, where the first few errors after runtime are always
+// kept, and the ones in the middle are increasingly likely to be omitted from
+// the history.
+
+import { Err } from "./types.js";
+
+// MAX_ERRORS defines the maximum number of errors that will be held in the
+// HistoricErr object.
+const MAX_ERRORS = 1000;
+
+// HistoricErr is a wrapper that adds a date to the Err type.
+interface HistoricErr {
+  err: Err;
+  date: Date;
+}
+
+// ErrTracker keeps track of errors that have happened, randomly dropping
+// errors to prevent the tracker from using too much memory if there happen to
+// be a large number of errors.
+interface ErrTracker {
+  recentErrs: HistoricErr[];
+  oldErrs: HistoricErr[];
+
+  addErr: (err: Err) => void;
+  viewErrs: () => HistoricErr[];
+}
+
+// newErrTracker returns an ErrTracker object that is ready to have errors
+// added to it.
+function newErrTracker(): ErrTracker {
+  const et: ErrTracker = {
+    recentErrs: [],
+    oldErrs: [],
+
+    addErr: function (err: Err): void {
+      addHistoricErr(et, err);
+    },
+    viewErrs: function (): HistoricErr[] {
+      return viewErrs(et);
+    },
+  };
+  return et;
+}
+
+// addHistoricErr is a function that will add an error to a set of historic
+// errors. It uses randomness to prune errors once the error object is too
+// large.
+function addHistoricErr(et: ErrTracker, err: Err): void {
+  // Add this error to the set of most recent errors.
+  et.recentErrs.push({
+    err,
+    date: new Date(),
+  });
+
+  // Determine whether some of the most recent errors need to be moved into
+  // logTermErrs. If the length of the mostRecentErrs is not at least half of
+  // the MAX_ERRORS, we don't need to do anything.
+  if (et.recentErrs.length < MAX_ERRORS / 2) {
+    return;
+  }
+
+  // Iterate through the recentErrs. For the first half of the recentErrs, we
+  // will use randomness to either toss them or move them to oldErrs. The
+  // second half of the recentErrs will be kept as the new recentErrs array.
+  const newRecentErrs : HistoricErr[] = [];
+  for (let i = 0; i < et.recentErrs.length; i++) {
+    // If we are in the second half of the array, add the element to
+    // newRecentErrs.
+    if (i > et.recentErrs.length / 2) {
+      newRecentErrs.push(et.recentErrs[i]);
+      continue;
+    }
+
+    // We are in the first half of the array, use a random number to add the
+    // error oldErrs probabilistically.
+    const rand = Math.random();
+    const target = et.oldErrs.length / (MAX_ERRORS / 2);
+    if (rand > target || et.oldErrs.length < 25) {
+      et.oldErrs.push(et.recentErrs[i]);
+    }
+  }
+  et.recentErrs = newRecentErrs;
+}
+
+// viewErrs returns the list of errors that have been retained by the
+// HistoricErr object.
+function viewErrs(et: ErrTracker): HistoricErr[] {
+  const finalErrs: HistoricErr[] = [];
+  for (let i = 0; i < et.oldErrs.length; i++) {
+    finalErrs.push(et.oldErrs[i]);
+  }
+  for (let i = 0; i < et.recentErrs.length; i++) {
+    finalErrs.push(et.recentErrs[i]);
+  }
+  return finalErrs;
+}
+
+export { ErrTracker, HistoricErr, newErrTracker };

src/index.ts

@@ -0,0 +1,12 @@
+import { ed25519 } from "@noble/curves/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+
+export * from "./err.js";
+export * from "./errTracker.js";
+export * from "./objAsString.js";
+export * from "./parse.js";
+export * from "./stringifyJSON.js";
+export * from "./types.js";
+export * from "./cid.js";
+export * from "./encoding.js";
+export { ed25519, sha512 };

src/objAsString.ts

@@ -0,0 +1,64 @@
+// objAsString will try to return the provided object as a string. If the
+// object is already a string, it will be returned without modification. If the
+// object is an 'Error', the message of the error will be returned. If the object
+// has a toString method, the toString method will be called and the result
+// will be returned. If the object is null or undefined, a special string will
+// be returned indicating that the undefined/null object cannot be converted to
+// a string. In all other cases, JSON.stringify is used. If JSON.stringify
+// throws an exception, a message "[could not provide object as string]" will
+// be returned.
+//
+// NOTE: objAsString is intended to produce human readable output. It is lossy,
+// and it is not intended to be used for serialization.
+function objAsString(obj: any): string {
+  // Check for undefined input.
+  if (obj === undefined) {
+    return "[cannot convert undefined to string]";
+  }
+  if (obj === null) {
+    return "[cannot convert null to string]";
+  }
+
+  // Parse the error into a string.
+  if (typeof obj === "string") {
+    return obj;
+  }
+
+  // Check if the object is an error, and return the message of the error if
+  // so.
+  if (obj instanceof Error) {
+    return obj.message;
+  }
+
+  // Check if the object has a 'toString' method defined on it. To ensure
+  // that we don't crash or throw, check that the toString is a function, and
+  // also that the return value of toString is a string.
+  if (Object.prototype.hasOwnProperty.call(obj, "toString")) {
+    if (typeof obj.toString === "function") {
+      const str = obj.toString();
+      if (typeof str === "string") {
+        return str;
+      }
+    }
+  }
+
+  // If the object does not have a custom toString, attempt to perform a
+  // JSON.stringify. We use a lot of bigints in libskynet, and calling
+  // JSON.stringify on an object with a bigint will cause a throw, so we add
+  // some custom handling to allow bigint objects to still be encoded.
+  try {
+    return JSON.stringify(obj, (_, v) => {
+      if (typeof v === "bigint") {
+        return v.toString();
+      }
+      return v;
+    });
+  } catch (err: any) {
+    if (err !== undefined && typeof err.message === "string") {
+      return `[stringify failed]: ${err.message}`;
+    }
+    return "[stringify failed]";
+  }
+}
+
+export { objAsString };

src/parse.ts

@@ -0,0 +1,376 @@
+// @ts-nocheck
+
+import { objAsString } from "./objAsString.js";
+import { Err } from "./types.js";
+
+// json_parse extracted from the json-bigint npm library
+// regexpxs extracted from
+// (c) BSD-3-Clause
+// https://github.com/fastify/secure-json-parse/graphs/contributors and https://github.com/hapijs/bourne/graphs/contributors
+const suspectProtoRx =
+  /(?:_|\\u005[Ff])(?:_|\\u005[Ff])(?:p|\\u0070)(?:r|\\u0072)(?:o|\\u006[Ff])(?:t|\\u0074)(?:o|\\u006[Ff])(?:_|\\u005[Ff])(?:_|\\u005[Ff])/;
+const suspectConstructorRx =
+  /(?:c|\\u0063)(?:o|\\u006[Ff])(?:n|\\u006[Ee])(?:s|\\u0073)(?:t|\\u0074)(?:r|\\u0072)(?:u|\\u0075)(?:c|\\u0063)(?:t|\\u0074)(?:o|\\u006[Ff])(?:r|\\u0072)/;
+let json_parse = function (options) {
+  "use strict";
+
+  // This is a function that can parse a JSON text, producing a JavaScript
+  // data structure. It is a simple, recursive descent parser. It does not use
+  // eval or regular expressions, so it can be used as a model for implementing
+  // a JSON parser in other languages.
+
+  // We are defining the function inside of another function to avoid creating
+  // global variables.
+
+  // Default options one can override by passing options to the parse()
+  let _options = {
+    strict: false, // not being strict means do not generate syntax errors for "duplicate key"
+    storeAsString: false, // toggles whether the values should be stored as BigNumber (default) or a string
+    alwaysParseAsBig: false, // toggles whether all numbers should be Big
+    protoAction: "error",
+    constructorAction: "error",
+  };
+
+  // If there are options, then use them to override the default _options
+  if (options !== undefined && options !== null) {
+    if (options.strict === true) {
+      _options.strict = true;
+    }
+    if (options.storeAsString === true) {
+      _options.storeAsString = true;
+    }
+    _options.alwaysParseAsBig = options.alwaysParseAsBig === true ? options.alwaysParseAsBig : false;
+
+    if (typeof options.constructorAction !== "undefined") {
+      if (
+        options.constructorAction === "error" ||
+        options.constructorAction === "ignore" ||
+        options.constructorAction === "preserve"
+      ) {
+        _options.constructorAction = options.constructorAction;
+      } else {
+        throw new Error(
+          `Incorrect value for constructorAction option, must be "error", "ignore" or undefined but passed ${options.constructorAction}`
+        );
+      }
+    }
+
+    if (typeof options.protoAction !== "undefined") {
+      if (options.protoAction === "error" || options.protoAction === "ignore" || options.protoAction === "preserve") {
+        _options.protoAction = options.protoAction;
+      } else {
+        throw new Error(
+          `Incorrect value for protoAction option, must be "error", "ignore" or undefined but passed ${options.protoAction}`
+        );
+      }
+    }
+  }
+
+  let at, // The index of the current character
+    ch, // The current character
+    escapee = {
+      '"': '"',
+      "\\": "\\",
+      "/": "/",
+      b: "\b",
+      f: "\f",
+      n: "\n",
+      r: "\r",
+      t: "\t",
+    },
+    text,
+    error = function (m) {
+      // Call error when something is wrong.
+
+      throw {
+        name: "SyntaxError",
+        message: m,
+        at: at,
+        text: text,
+      };
+    },
+    next = function (c) {
+      // If a c parameter is provided, verify that it matches the current character.
+
+      if (c && c !== ch) {
+        error("Expected '" + c + "' instead of '" + ch + "'");
+      }
+
+      // Get the next character. When there are no more characters,
+      // return the empty string.
+
+      ch = text.charAt(at);
+      at += 1;
+      return ch;
+    },
+    number = function () {
+      // Parse a number value.
+
+      let number,
+        string = "";
+
+      if (ch === "-") {
+        string = "-";
+        next("-");
+      }
+      while (ch >= "0" && ch <= "9") {
+        string += ch;
+        next();
+      }
+      if (ch === ".") {
+        string += ".";
+        while (next() && ch >= "0" && ch <= "9") {
+          string += ch;
+        }
+      }
+      if (ch === "e" || ch === "E") {
+        string += ch;
+        next();
+        if (ch === "-" || ch === "+") {
+          string += ch;
+          next();
+        }
+        while (ch >= "0" && ch <= "9") {
+          string += ch;
+          next();
+        }
+      }
+      number = +string;
+      if (!isFinite(number)) {
+        error("Bad number");
+      } else {
+        if (Number.isSafeInteger(number)) return !_options.alwaysParseAsBig ? number : BigInt(number);
+        // Number with fractional part should be treated as number(double) including big integers in scientific notation, i.e 1.79e+308
+        else return _options.storeAsString ? string : /[.eE]/.test(string) ? number : BigInt(string);
+      }
+    },
+    string = function () {
+      // Parse a string value.
+
+      let hex,
+        i,
+        string = "",
+        uffff;
+
+      // When parsing for string values, we must look for " and \ characters.
+
+      if (ch === '"') {
+        let startAt = at;
+        while (next()) {
+          if (ch === '"') {
+            if (at - 1 > startAt) string += text.substring(startAt, at - 1);
+            next();
+            return string;
+          }
+          if (ch === "\\") {
+            if (at - 1 > startAt) string += text.substring(startAt, at - 1);
+            next();
+            if (ch === "u") {
+              uffff = 0;
+              for (i = 0; i < 4; i += 1) {
+                hex = parseInt(next(), 16);
+                if (!isFinite(hex)) {
+                  break;
+                }
+                uffff = uffff * 16 + hex;
+              }
+              string += String.fromCharCode(uffff);
+            } else if (typeof escapee[ch] === "string") {
+              string += escapee[ch];
+            } else {
+              break;
+            }
+            startAt = at;
+          }
+        }
+      }
+      error("Bad string");
+    },
+    white = function () {
+      // Skip whitespace.
+
+      while (ch && ch <= " ") {
+        next();
+      }
+    },
+    word = function () {
+      // true, false, or null.
+
+      switch (ch) {
+        case "t":
+          next("t");
+          next("r");
+          next("u");
+          next("e");
+          return true;
+        case "f":
+          next("f");
+          next("a");
+          next("l");
+          next("s");
+          next("e");
+          return false;
+        case "n":
+          next("n");
+          next("u");
+          next("l");
+          next("l");
+          return null;
+      }
+      error("Unexpected '" + ch + "'");
+    },
+    value, // Place holder for the value function.
+    array = function () {
+      // Parse an array value.
+
+      let array = [];
+
+      if (ch === "[") {
+        next("[");
+        white();
+        if (ch === "]") {
+          next("]");
+          return array; // empty array
+        }
+        while (ch) {
+          array.push(value());
+          white();
+          if (ch === "]") {
+            next("]");
+            return array;
+          }
+          next(",");
+          white();
+        }
+      }
+      error("Bad array");
+    },
+    object = function () {
+      // Parse an object value.
+
+      let key,
+        object = Object.create(null);
+
+      if (ch === "{") {
+        next("{");
+        white();
+        if (ch === "}") {
+          next("}");
+          return object; // empty object
+        }
+        while (ch) {
+          key = string();
+          white();
+          next(":");
+          if (_options.strict === true && Object.hasOwnProperty.call(object, key)) {
+            error('Duplicate key "' + key + '"');
+          }
+
+          if (suspectProtoRx.test(key) === true) {
+            if (_options.protoAction === "error") {
+              error("Object contains forbidden prototype property");
+            } else if (_options.protoAction === "ignore") {
+              value();
+            } else {
+              object[key] = value();
+            }
+          } else if (suspectConstructorRx.test(key) === true) {
+            if (_options.constructorAction === "error") {
+              error("Object contains forbidden constructor property");
+            } else if (_options.constructorAction === "ignore") {
+              value();
+            } else {
+              object[key] = value();
+            }
+          } else {
+            object[key] = value();
+          }
+
+          white();
+          if (ch === "}") {
+            next("}");
+            return object;
+          }
+          next(",");
+          white();
+        }
+      }
+      error("Bad object");
+    };
+
+  value = function () {
+    // Parse a JSON value. It could be an object, an array, a string, a number,
+    // or a word.
+
+    white();
+    switch (ch) {
+      case "{":
+        return object();
+      case "[":
+        return array();
+      case '"':
+        return string();
+      case "-":
+        return number();
+      default:
+        return ch >= "0" && ch <= "9" ? number() : word();
+    }
+  };
+
+  // Return the json_parse function. It will have access to all of the above
+  // functions and variables.
+
+  return function (source, reviver) {
+    let result;
+
+    text = source + "";
+    at = 0;
+    ch = " ";
+    result = value();
+    white();
+    if (ch) {
+      error("Syntax error");
+    }
+
+    // If there is a reviver function, we recursively walk the new structure,
+    // passing each name/value pair to the reviver function for possible
+    // transformation, starting with a temporary root object that holds the result
+    // in an empty key. If there is not a reviver function, we simply return the
+    // result.
+
+    return typeof reviver === "function"
+      ? (function walk(holder, key) {
+          let v,
+            value = holder[key];
+          if (value && typeof value === "object") {
+            Object.keys(value).forEach(function (k) {
+              v = walk(value, k);
+              if (v !== undefined) {
+                value[k] = v;
+              } else {
+                delete value[k];
+              }
+            });
+          }
+          return reviver.call(holder, key, value);
+        })({ "": result }, "")
+      : result;
+  };
+};
+
+// parseJSON is a wrapper for JSONbig.parse that returns an error rather than
+// throwing an error. JSONbig is an alternative to JSON.parse that decodes
+// every number as a bigint. This is required when working with the skyd API
+// because the skyd API uses 64 bit precision for all of its numbers, and
+// therefore cannot be parsed losslessly by javascript. The skyd API is
+// cryptographic, therefore full precision is required.
+function parseJSON(json: string): [any, Err] {
+  try {
+    let obj = json_parse({ alwaysParseAsBig: true })(json);
+    return [obj, null];
+  } catch (err: any) {
+    return [{}, objAsString(err)];
+  }
+}
+
+export { parseJSON };

src/stringifyJSON.ts

@@ -0,0 +1,21 @@
+import { addContextToErr } from "./err.js";
+import { objAsString } from "./objAsString.js";
+import { Err } from "./types.js";
+
+// jsonStringify is a replacement for JSON.stringify that returns an error
+// rather than throwing.
+function jsonStringify(obj: any): [string, Err] {
+  try {
+    const str = JSON.stringify(obj, (_, v) => {
+      if (typeof v === "bigint") {
+        return Number(v);
+      }
+      return v;
+    });
+    return [str, null];
+  } catch (err) {
+    return ["", addContextToErr(objAsString(err), "unable to stringify object")];
+  }
+}
+
+export { jsonStringify };

src/types.ts

@@ -0,0 +1,82 @@
+// DataFn can take any object as input and has no return value. The input is
+// allowed to be undefined.
+type DataFn = (data?: any) => void;
+
+// Err is an error type that is either a string or a null. If the value is
+// null, that indicates that there was no error. If the value is a string, it
+// indicates that there was an error and the string contains the error message.
+//
+// The skynet libraries prefer this error type to the standard Error type
+// because many times skynet libraries need to pass errors over postMessage,
+// and the 'Error' type is not able to be sent over postMessage.
+type Err = string | null;
+
+// ErrFn must take an error message as input. The input is not allowed to be
+// undefined or null, there must be an error.
+type ErrFn = (errMsg: string) => void;
+
+// ErrTuple is a type that pairs a 'data' field with an 'err' field. Skynet
+// libraries typically prefer returning ErrTuples to throwing or rejecting,
+// because it allows upstream code to avoid the try/catch/throw pattern. Though
+// the pattern is much celebrated in javascript, it encourages relaxed error
+// handling, and often makes error handling much more difficult because the try
+// and the catch are in different scopes.
+//
+// Most of the Skynet core libraries do not have any `throws` anywhere in their
+// API.
+//
+// Typically, an ErrTuple will have only one field filled out. If data is
+// returned, the err should be 'null'. If an error is returned, the data field
+// should generally be empty. Callers are expected to check the error before
+// they access any part of the data field.
+type ErrTuple = [data: any, err: Err];
+
+// KernelAuthStatus is the structure of a message that gets sent by the kernel
+// containing its auth status. Auth occurs in 5 stages.
+//
+// Stage 0; no auth updates
+// Stage 1: bootloader is loaded, user is not yet logged in
+// Stage 2: bootloader is loaded, user is logged in
+// Stage 3: kernel is loaded, user is logged in
+// Stage 4: kernel is loaded, user is logging out (refresh iminent)
+//
+// 'kernelLoaded' is initially set to "not yet" and will be updated when the
+// kernel has loaded. If it is set to "success", it means the kernel loaded
+// without issues. If it is set to anything else, it means that there was an
+// error, and the new value is the error.
+//
+// 'kernelLoaded' will not be changed until 'loginComplete' has been set to
+// true. 'loginComplete' can be set to true immediately if the user is already
+// logged in.
+//
+// 'logoutComplete' can be set to 'true' at any point, which indicates that the
+// auth cycle needs to reset.
+interface KernelAuthStatus {
+  loginComplete: boolean;
+  kernelLoaded: "not yet" | "success" | string;
+  logoutComplete: boolean;
+}
+
+interface Portal {
+  id: string;
+  name: string;
+  url: string;
+}
+
+// RequestOverrideResponse defines the type that the kernel returns as a
+// response to a requestOverride call.
+interface RequestOverrideResponse {
+  override: boolean;
+  headers?: any; // TODO: I don't know how to do an array of types.
+  body?: Uint8Array;
+}
+
+export {
+  DataFn,
+  ErrFn,
+  Err,
+  ErrTuple,
+  KernelAuthStatus,
+  RequestOverrideResponse,
+  Portal,
+};