documentation updates

lib/relative-random-time/index.ts

@@ -10,7 +10,10 @@ const NEAR_SMALLEST_ABS = 10**3;
 
 const dateTLS = (time: number): string => (!isFinite(time) && time.toString()) || (new Date(time)).toLocaleString();
 
-// TODO: document that bounds are inclusive
+/**
+ * Returns a number between bounds[0] and bounds[1] (inclusive) that is higher
+ * than `before` but lower than `after`.
+ */
 export function fromTimespan({ bounds, before, after }: TimespanParams): number {
     // ? Ensure sorting happens in ascending order
     bounds.sort((a, b) => a - b);
@@ -27,22 +30,41 @@ export function fromTimespan({ bounds, before, after }: TimespanParams): number
     return randomInt(ceiling, floor);
 }
 
+/**
+ * Returns a number that is higher than `before` but lower than `after`
+ * representing a time in the distant past (months to decades).
+ */
 export function farPast({ before, after }: TimeParams = {}): number {
     return fromTimespan({ bounds: [-FAR_SMALLEST_ABS, -FAR_LARGEST_ABS], before, after });
 }
 
+/**
+ * Returns a number that is higher than `before` but lower than `after`
+ * representing a time in the near past (seconds to minutes).
+ */
 export function nearPast({ before, after }: TimeParams = {}): number {
     return fromTimespan({ bounds: [-NEAR_SMALLEST_ABS, -NEAR_LARGEST_ABS], before, after });
 }
 
+/**
+ * Returns Date.now()
+ */
 export function present(): number {
     return Date.now();
 }
 
+/**
+ * Returns a number that is higher than `before` but lower than `after`
+ * representing a time in the distant future (months to decades).
+ */
 export function nearFuture({ before, after }: TimeParams = {}): number {
     return fromTimespan({ bounds: [NEAR_SMALLEST_ABS, NEAR_LARGEST_ABS], before, after });
 }
 
+/**
+ * Returns a number that is higher than `before` but lower than `after`
+ * representing a time in the near future (seconds to minutes).
+ */
 export function farFuture({ before, after }: TimeParams = {}): number {
     return fromTimespan({ bounds: [FAR_SMALLEST_ABS, FAR_LARGEST_ABS], before, after });
 }

lib/test-api-endpoint.ts

@@ -14,6 +14,24 @@ export type TesApiEndParams = {
     next: any;
 };
 
+/**
+ * Uses Next's internal `apiResolver` to execute endpoints in a Next-like
+ * testing environment. Useful for unit testing Next /api endpoints.
+ *
+ * `test` should be a function that returns a promise (or async) where Jest
+ * tests and the like can be run.
+ *
+ * `params` are passed directly to the api handler and represent processed
+ * dynamic routes, i.e. testing `/api/user/:id` would need `params: { id: ... }`
+ *
+ * `requestPatcher` and `responsePatcher` are functions that receive an
+ * IncomingMessage and ServerResponse instance respectively. Use these functions
+ * to edit the request and response before they're injected into the api
+ * handler.
+ *
+ * `next` is the actual api handler under test. It should be an async function
+ * that accepts a NextApiRequest and NextApiResult as its two parameters.
+ */
 export async function testApiEndpoint({ test, params, requestPatcher, responsePatcher, next }: TesApiEndParams) {
     let server = null;
 

package.json

@@ -72,7 +72,6 @@
     "cors": "^2.8.5",
     "dotenv": "^8.2.0",
     "dotenv-webpack": "^1.8.0",
-    "eslint-import-resolver-alias": "^1.1.2",
     "fast-shuffle": "^3.0.0",
     "isomorphic-unfetch": "^3.0.0",
     "mongodb": "^3.5.7",
@@ -111,6 +110,7 @@
     "eslint-plugin-import": "^2.20.2",
     "eslint-plugin-jsx-a11y": "^6.2.3",
     "eslint-plugin-react": "^7.20.0",
+    "eslint-import-resolver-alias": "^1.1.2",
     "fancy-log": "^1.3.3",
     "gulp": "^4.0.2",
     "gulp-tap": "^2.0.0",

src/__test__/db.ts

@@ -148,7 +148,6 @@ export const unhydratedDummyDbData: DummyDbData = {
     ].flat()
 };
 
-// TODO: not idempotent; elections will be duplicated if called twice
 export async function hydrateDb(db: Db, data: DummyDbData): Promise<DummyDbData> {
     const newData = { ...data };
 

src/backend/db.ts

@@ -17,7 +17,10 @@ export async function getDb(): Promise<Db> {
  */
 export function setDb(newDB: Db): void { db = newDB; }
 
-// TODO: document
+/**
+ * Destroys all collections in the database. Can be called multiple times
+ * safely.
+ */
 export async function destroyDb(db: Db) {
     await Promise.allSettled([
         db.dropCollection('keys'),
@@ -28,13 +31,12 @@ export async function destroyDb(db: Db) {
     ]);
 }
 
-// TODO: document that this function is idempotent and can be called on
-// TODO: conformant databases that already have the appropriate structure
-// TODO: without worry of data loss
+/**
+ * This function is idempotent and can be called without worry of data loss.
+ */
 export async function initializeDb(db: Db): Promise<void> {
-    // TODO: add validation rules during createCollection phase
-    // TODO: (including special 0 root key not accepted in keys or in API)
-    // TODO: also make an index over key in keys (if not exists)
+    // TODO: Add validation rules during createCollection phase
+    // TODO: Make an index over key in keys (if not exists)
 
     await Promise.all([
         db.createCollection('keys'),