chore: Adds types with js-docs

README.md

@@ -7,7 +7,7 @@ Originally developed by annaleigh, austin, clem, culi, daniella.
 * `npm`
 
 ## technology
-this ancient front-end was made with create-react-app. it does not utilize typescript but is moving towards type safety with js-docs which [is a full-featured alternative to typescript](https://github.com/sveltejs/kit/discussions/4429#discussioncomment-2423814) that runs on the same engine.
+this ancient front-end was made with create-react-app. it does not utilize typescript but is moving towards type safety with js-docs which [is a full-featured alternative to typescript](https://github.com/sveltejs/kit/discussions/4429#discussioncomment-2423814) that runs on the same engine!
 
 ## setup
 0. clone down (`git clone [email protected]:openbookbook/bookbook-web.git`) and `cd ./bookbook-web`

src/pages/ballot/BallotPage.js

@@ -6,7 +6,9 @@ import AdminPanel from './AdminPanel';
 import ResultsPanel from './ResultsPanel';
 import './BallotPage.css';
 
+/** @typedef {{ match: import('react-router-dom').RouteComponentProps['match'] }} BallotPageProps */
 
+/** @param {BallotPageProps} props */
 const BallotPage = props => {
   const {
     loading, ballot,
@@ -49,7 +51,7 @@ const BallotPage = props => {
       />
     </>}
 
-    {Boolean(ballot?.endDate) 
+    {Boolean(ballot?.endDate)
       ? <>
         <span className="panel-title">results</span>
         <ResultsPanel

src/pages/setup/PermissionsPanel.js

@@ -1,11 +1,20 @@
 import React from 'react';
 
+/**
+ * @typedef {{
+ *   setVoteCode: React.Dispatch<React.SetStateAction<string>>;
+ * }} PermissionsPanelProps
+ */
+
+/** @param {PermissionsPanelProps} props */
 const PermissionsPanel = props => {
   const {
     setVoteCode,
     enableVoteCodeInput,
     setEnableVoteCodeInput
   } = props;
+
+  /** @type {React.ChangeEventHandler<HTMLInputElement>} */
   const handleTextChange = e => setVoteCode(e.target.value);
 
   return (

src/pages/setup/SuggestPanel.js

@@ -59,7 +59,7 @@ const SuggestPanel = props => {
       />
 
       <ul className="book-display list-view">
-        {results.filter(
+        {(results || []).filter(
           book => !suggestions.some(suggestion => suggestion.gbooks === book.googleId)
         ).map(book => (
           <li className="search-result" key={book.googleId}>

src/state/useBallot.js

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react';
-import { addUser, getBallot, getSuggestions, getUsers, loginUser, updateBallot, updateUser as putUser, patchUser } from '../utils/backend-api';
+import { addUser, getBallot, getSuggestions, getUsers, loginUser, updateBallot, patchUser } from '../utils/backend-api';
 import { getBook } from '../utils/gbooks-api';
 import { base62, relocateItemInArray, shuffleArray } from '../utils/utils';
 import { rankedChoiceVote } from '../utils/voting-methods';
@@ -13,6 +13,7 @@ const updateUserVote = async user => {
   return await patchUser(user, ['vote', user.vote]);
 };
 
+/** @param {string} idFromUrl */
 const useBallot = idFromUrl => {
   const [ballot, setBallot] = useState(null);
   const [users, setUsers] = useState([]);
@@ -121,6 +122,7 @@ const useBallot = idFromUrl => {
     setUsers(users.map(u => u.id === currentUser.id ? currentUser : u));
   };
 
+  /** @param {number} oldIndex; @param {number} newIndex */
   const handleRankingChange = (oldIndex, newIndex) => {
     const newRanking = relocateItemInArray(currentRanking.map(c => c.id), oldIndex, newIndex);
     setCurrentRanking(newRanking.map(id => currentRanking.find(c => c.id === id)));

src/state/useGoogleBooks.js

@@ -1,9 +1,13 @@
 import { useCallback, useState } from 'react';
 import { searchBooks } from '../utils/gbooks-api';
 
+/** @typedef {import('../utils/gbooks-api').Book} Book */
+
 const useGoogleBooks = () => {
-  const [results, setResults] = useState([]);
+  /** @type {ReturnType<typeof useState<Book[]>>} */
+  const [results, setResults] = useState();
 
+  /** @type {React.ChangeEventHandler<HTMLInputElement>} */
   const handleSearch = useCallback(
     async e => {
       let query = e.target.value;

src/state/useSetup.js

@@ -1,12 +1,13 @@
 import { useState } from 'react';
 import { useHistory } from 'react-router';
-import { 
-  addBallot as postBallot, 
-  addSuggestion as postSuggestion 
+import {
+  addBallot as postBallot,
+  addSuggestion as postSuggestion
 } from '../utils/backend-api';
 import { base62 } from '../utils/utils';
 
 const useSetup = () => {
+  /** @type {[string, React.Dispatch<React.SetStateAction<string>>]} */
   const [errorMessage, setErrorMessage] = useState('');
   const [ballotName, setBallotName] = useState('');
   const [adminCode, setAdminCode] = useState('');
@@ -17,11 +18,11 @@ const useSetup = () => {
 
   const history = useHistory();
 
-  const addSuggestion = (suggestion, type = 'book') => 
+  const addSuggestion = (suggestion, _type = 'book') =>
     setSuggestions([...suggestions, suggestion])
   ;
 
-  const deleteSuggestion = (val, key = 'gbooks') => 
+  const deleteSuggestion = (val, key = 'gbooks') =>
     setSuggestions(suggestions.filter(s => s[key] !== val));
   ;
 

src/utils/backend-api.js

@@ -5,6 +5,11 @@ const URL = process.env.NODE_ENV === 'development'
   : 'https://openbookbook.herokuapp.com'
 ;
 
+/**
+ * @param {'get' | 'post' | 'put' | 'patch' | 'delete'} method
+ * @param {string} path
+ * @template Dto @param {Dto} [data]
+ */
 const req = async (method, path, data) => {
   try {
     return (data
@@ -16,6 +21,7 @@ const req = async (method, path, data) => {
     return { error: err.message };
   }
 };
+/** @param {string} path; @template T @param {T} data */
 const postReq = async (path, data) => await req('post', path, data);
 const getReq = async (path) => await req('get', path);
 const putReq = async (path, data) => await req('put', path, data);

src/utils/gbooks-api.js

@@ -2,6 +2,7 @@ import request from 'superagent';
 
 const GBOOKS_API = 'https://www.googleapis.com/books/v1/volumes';
 
+/** @returns {Promise<Book[]>} */
 async function searchBooks(query, printType = 'books') {
   const response = await request
     .get(GBOOKS_API)
@@ -20,6 +21,21 @@ async function getBook(gbooks) {
   return mungeBook(response.body);
 }
 
+/**
+ * @typedef {{
+ *   authors: string[];
+ *   description: string;
+ *   googleId: string;
+ *   image: string;
+ *   pageCount: number;
+ *   price: number | undefined;
+ *   subtitle: string;
+ *   title: string;
+ * }} Book
+ *
+ * @param {Object} book
+ * @returns {Book}
+ */
 function mungeBook(book) {
   return {
     authors: book.volumeInfo.authors || [],

src/utils/utils.js

@@ -1,12 +1,14 @@
-export function getByProperty(arr, val, prop = 'id') {
-  // this is exactly like findById(arr, val) if the prop parameter isn't specified
-  return arr.filter(obj => obj[prop] === val)[0];
-}
-
+/**
+ * @template T @param {Array<T>} arr
+ * @param {number} oldIndex
+ * @param {number} newIndex
+ */
 export function relocateItemInArray(arr, oldIndex, newIndex) {
   // Here's a much more complicated, but more memory efficient (faster) one I found online:
   let i, tmp;
+  // @ts-ignore
   oldIndex = parseInt(oldIndex, 10);
+  // @ts-ignore
   newIndex = parseInt(newIndex, 10);
 
   if (oldIndex !== newIndex && 0 <= oldIndex && oldIndex <= arr.length && 0 <= newIndex && newIndex <= arr.length) {
@@ -27,6 +29,7 @@ export function relocateItemInArray(arr, oldIndex, newIndex) {
   return arr;
 }
 
+/** @template T @param {Array<T>} arr */
 export function shuffleArray(arr) {
   const array = [...arr];
   for (let i = (array.length - 1); i > 0; i--) {
@@ -38,8 +41,9 @@ export function shuffleArray(arr) {
 
 export const base62 = {
   charset: '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'.split(''),
+  /** @param {number} integer */
   encode: integer => {
-    if (integer === 0) return 0;
+    if (integer === 0) return '0';
 
     let s = [];
     while (integer > 0) {
@@ -48,5 +52,6 @@ export const base62 = {
     }
     return s.join('');
   },
+  /** @param {string} chars */
   decode: chars => chars.split('').reverse().reduce((prev, curr, i) => prev + (base62.charset.indexOf(curr) * (62 ** i)), 0)
 };