dce-commonkit 4.4.0

package/src/helpers/validators/validateString.test.ts

@@ -0,0 +1,173 @@
+// Import helpers
+import genCommaList from '../genCommaList';
+
+// Import types
+import ValidationResult from './shared/types/ValidationResult';
+
+// Import constants
+import { INVALID_STRING_ERRORS, INVALID_REGEX_ERROR } from './shared/constants/ERROR_MESSAGES';
+
+// Import function
+import validateString from './validateString';
+
+/*------------------------------------------------------------------------*/
+/* ---------------------------- Valid Tests --------------------------- */
+/*------------------------------------------------------------------------*/
+
+const validStrings: string[] = [
+  'users',
+  'username',
+  'MyValidString',
+  'HereisAnotherValidString',
+  'WoahAnotherValidStringIsHere',
+];
+
+const validReqs: {
+  // whitespace is removed from input before checking and returning
+  ignoreWhitespace?: boolean,
+  // input length must be at least minLen
+  minLen?: number,
+  // input length must be at most maxLen
+  maxLen?: number,
+  // input must only contain letters
+  lettersOnly?: boolean,
+  // input must only contain numbers
+  numbersOnly?: boolean,
+  // input must match given regExp
+  regexTest?: RegExp,
+  // description of regExp test, used to customize error messages
+  regexDescription?: string,
+}[] = [
+  {
+  },
+  {
+    minLen: 5,
+  },
+  {
+    minLen: 5,
+    maxLen: 30,
+  },
+  {
+    minLen: 5,
+    maxLen: 30,
+    lettersOnly: true,
+  },
+  {
+    minLen: 5,
+    maxLen: 30,
+    lettersOnly: true,
+    numbersOnly: false,
+  },
+  {
+    minLen: 5,
+    maxLen: 30,
+    lettersOnly: true,
+    numbersOnly: false,
+    ignoreWhitespace: false,
+  },
+];
+
+test(
+  'Returns true for a given valid string.',
+  async () => {
+    validStrings.forEach((validString) => {
+      validReqs.forEach((validReq) => {
+        const validResponse: ValidationResult<string> = {
+          isValid: true,
+          cleanedValue: validString,
+        };
+
+        expect(validateString(validString, validReq)).toStrictEqual(validResponse);
+      });
+    });
+
+    const validString = 'A string with whitespace!';
+
+    const validResponse: ValidationResult<string> = {
+      isValid: true,
+      cleanedValue: 'Astringwithwhitespace!',
+    };
+
+    const validOpt = {
+      maxLen: 22,
+      ignoreWhitespace: true,
+    };
+
+    expect(validateString(validString, validOpt)).toStrictEqual(validResponse);
+  },
+);
+
+/*------------------------------------------------------------------------*/
+/* ---------------------------- Invalid Tests --------------------------- */
+/*------------------------------------------------------------------------*/
+
+const invalidStrings: {
+  input: string,
+  reqs: {
+    // whitespace is removed from input before checking and returning
+    ignoreWhitespace?: boolean,
+    // input length must be at least minLen
+    minLen?: number,
+    // input length must be at most maxLen
+    maxLen?: number,
+    // input must only contain letters
+    lettersOnly?: boolean,
+    // input must only contain numbers
+    numbersOnly?: boolean,
+    // input must match given regExp
+    regexTest?: RegExp,
+    // description of regExp test, used to customize error messages
+    regexDescription?: string,
+  },
+  error: string[]
+}[] = [
+  {
+    input: 'ûšër',
+    reqs: {
+      minLen: 5,
+      lettersOnly: true,
+    },
+    error: [INVALID_STRING_ERRORS.MIN_LEN(5)],
+  },
+  {
+    input: '123456789',
+    reqs: {
+      minLen: 10,
+      maxLen: 5,
+      lettersOnly: true,
+    },
+    error: [INVALID_STRING_ERRORS.MIN_LEN(10), INVALID_STRING_ERRORS.MAX_LEN(5), INVALID_STRING_ERRORS.LETTERS_ONLY],
+  },
+  {
+    input: 'String with non-letters!!',
+    reqs: {
+      lettersOnly: true,
+      numbersOnly: true,
+      ignoreWhitespace: true,
+    },
+    error: [INVALID_STRING_ERRORS.LETTERS_ONLY, INVALID_STRING_ERRORS.NUMBERS_ONLY],
+  },
+  {
+    input: '12345678',
+    reqs: {
+      lettersOnly: true,
+      regexTest: /^\s*(?:\+?(\d{1,3}))?[-. (]*(\d{3})[-. )]*(\d{3})[-. ]*(\d{4})(?: *x(\d+))?\s*$/,
+      regexDescription: 'should be a phone number',
+    },
+    error: [INVALID_STRING_ERRORS.LETTERS_ONLY, `${INVALID_REGEX_ERROR}: should be a phone number`],
+  },
+];
+
+test(
+  'Returns false for a given invalid string.',
+  async () => {
+    invalidStrings.forEach((triple) => {
+      const invalidResponse: ValidationResult<string> = {
+        isValid: false,
+        errorMessage: `${INVALID_STRING_ERRORS.MESSAGE_INTRO}${genCommaList(triple.error)}.`,
+      };
+
+      expect(validateString(triple.input, triple.reqs)).toStrictEqual(invalidResponse);
+    });
+  },
+);

package/src/helpers/validators/validateString.ts

@@ -0,0 +1,171 @@
+// Import helpers
+import validateRegex from './shared/helpers/validateRegex';
+import genCommaList from '../genCommaList';
+
+// Import constants
+import { INVALID_STRING_ERRORS } from './shared/constants/ERROR_MESSAGES';
+
+// Import types
+import ValidationResult from './shared/types/ValidationResult';
+
+/*------------------------------------------------------------------------*/
+/* ------------------------------ Constants ----------------------------- */
+/*------------------------------------------------------------------------*/
+
+// define minimum and maximum range for lowercase ASCII chars
+const LOWERCASE_MIN = 65;
+const LOWERCASE_MAX = 90;
+
+// define minimum and maximum range for uppercase ASCII chars
+const UPPERCASE_MIN = 97;
+const UPPERCASE_MAX = 122;
+
+// define minimum and maximum range for ASCII digits
+const DIGIT_MIN = 48;
+const DIGIT_MAX = 57;
+
+/*------------------------------------------------------------------------*/
+/* ---------------------------- Main Function --------------------------- */
+/*------------------------------------------------------------------------*/
+
+/**
+ * Determines whether a given input string is considered valid based on
+ *   the provided requirements.
+ * @author Austen Money
+ * @param input input string
+ * @param opts options for validation
+ * @returns whether input is considered valid according to reqs - if
+ *   valid, returns a cleaned version of input; if invalid, returns
+ *   a string containing error messages describing which requirements
+ *   were not met.
+ */
+const validateString = (
+  input: string,
+  opts: {
+    // whitespace is removed from input before checking and returning
+    ignoreWhitespace?: boolean,
+    // input length must be at least minLen
+    minLen?: number,
+    // input length must be at most maxLen
+    maxLen?: number,
+    // input must only contain letters
+    // (future TODO: add option for passing in an array of permitted chars)
+    lettersOnly?: boolean,
+    // input must only contain numbers
+    numbersOnly?: boolean,
+    // input must match given regExp
+    regexTest?: RegExp,
+    // description of regExp test, used to customize error messages
+    regexDescription?: string,
+  },
+): ValidationResult<string> => {
+  // stores all invalid input errors
+  const errorMessages: string[] = [];
+
+  // contains version of input that will be returned
+  let cleanedValue: string = input;
+
+  // remove whitespace if required
+  if (opts.ignoreWhitespace) {
+    cleanedValue = input.replace(/\s+/g, '');
+  }
+
+  // apply max char requirement
+  if (opts.minLen) {
+    if (cleanedValue.length < opts.minLen) {
+      errorMessages.push(INVALID_STRING_ERRORS.MIN_LEN(opts.minLen));
+    }
+  }
+
+  // apply max char requirement
+  if (opts.maxLen) {
+    if (cleanedValue.length > opts.maxLen) {
+      errorMessages.push(INVALID_STRING_ERRORS.MAX_LEN(opts.maxLen));
+    }
+  }
+
+  // apply alphabetical requirement
+  if (opts.lettersOnly) {
+    // remove diacritics
+    cleanedValue = cleanedValue.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+
+    const containsNonLetters = (
+      cleanedValue
+        // split into characters
+        .split('')
+        // convert into character codes
+        .map((curr) => {
+          return curr.charCodeAt(0);
+        })
+        // check for non-letters
+        .some((currCode) => {
+          return (
+            !(currCode >= LOWERCASE_MIN && currCode <= LOWERCASE_MAX)
+            && !(currCode >= UPPERCASE_MIN && currCode <= UPPERCASE_MAX)
+          );
+        })
+    );
+
+    if (containsNonLetters) {
+      errorMessages.push(INVALID_STRING_ERRORS.LETTERS_ONLY);
+    }
+  }
+
+  // apply numerical requirement
+  if (opts.numbersOnly) {
+    const containsNonNumbers = (
+      cleanedValue
+        // split into characters
+        .split('')
+        // convert into character codes
+        .map((curr) => {
+          return curr.charCodeAt(0);
+        })
+        // check for non-numbers
+        .some((currCode) => {
+          return (
+            !(currCode >= DIGIT_MIN && currCode <= DIGIT_MAX)
+          );
+        })
+    );
+
+    if (containsNonNumbers) {
+      errorMessages.push(INVALID_STRING_ERRORS.NUMBERS_ONLY);
+    }
+  }
+
+  // apply regex requirement
+  if (opts.regexTest) {
+    const regex = opts.regexTest;
+
+    // validate and create customized error message if description is provided
+    const result = validateRegex({
+      input: cleanedValue,
+      regex,
+      regexDescription: opts.regexDescription,
+    });
+
+    // if string did not pass regex validation, add error message
+    if (result.isValid === false) {
+      errorMessages.push(result.errorMessage);
+    }
+  }
+
+  // combine all error messages into one string to return
+  const errorMessage = `${INVALID_STRING_ERRORS.MESSAGE_INTRO}${genCommaList(errorMessages)}.`;
+
+  return (
+    // if no error messages, string is valid; if not, it is invalid
+    errorMessages.length === 0
+      ? {
+        isValid: true,
+        cleanedValue,
+      }
+      : {
+        isValid: false,
+        errorMessage,
+      }
+  );
+};
+
+export default validateString;

package/src/helpers/waitMs.ts

@@ -0,0 +1,12 @@
+/**
+ * Wait for a certain number of ms
+ * @author Gabe Abrams
+ * @param ms number of ms to wait
+ */
+const waitMs = async (ms = 0) => {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+};
+
+export default waitMs;

package/src/index.ts

@@ -0,0 +1,139 @@
+// Import errors
+import ErrorWithCode from './errors/ErrorWithCode';
+
+// Import constants
+import MINUTE_IN_MS from './constants/MINUTE_IN_MS';
+import HOUR_IN_MS from './constants/HOUR_IN_MS';
+import DAY_IN_MS from './constants/DAY_IN_MS';
+import LOG_REVIEW_ROUTE_PATH_PREFIX from './constants/LOG_REVIEW_ROUTE_PATH_PREFIX';
+import LOG_ROUTE_PATH from './constants/LOG_ROUTE_PATH';
+import LOG_REVIEW_STATUS_ROUTE from './constants/LOG_REVIEW_STATUS_ROUTE';
+import LOG_REVIEW_GET_LOGS_ROUTE from './constants/LOG_REVIEW_GET_LOGS_ROUTE';
+import SELECT_ADMIN_CHECK_ROUTE from './constants/SELECT_ADMIN_CHECK_ROUTE';
+
+// Import helpers
+import abbreviate from './helpers/abbreviate';
+import avg from './helpers/avg';
+import ceilToNumDecimals from './helpers/ceilToNumDecimals';
+import floorToNumDecimals from './helpers/floorToNumDecimals';
+import forceNumIntoBounds from './helpers/forceNumIntoBounds';
+import padDecimalZeros from './helpers/padDecimalZeros';
+import padZerosLeft from './helpers/padZerosLeft';
+import roundToNumDecimals from './helpers/roundToNumDecimals';
+import sum from './helpers/sum';
+import waitMs from './helpers/waitMs';
+import getOrdinal from './helpers/getOrdinal';
+import getTimeInfoInET from './helpers/getTimeInfoInET';
+import startMinWait from './helpers/startMinWait';
+import getHumanReadableDate from './helpers/getHumanReadableDate';
+import getPartOfDay from './helpers/getPartOfDay';
+import stringsToHumanReadableList from './helpers/stringsToHumanReadableList';
+import onlyKeepLetters from './helpers/onlyKeepLetters';
+import parallelLimit from './helpers/parallelLimit';
+import getMonthName from './helpers/getMonthName';
+import genCSV from './helpers/genCSV';
+import extractProp from './helpers/extractProp';
+import compareArraysByProp from './helpers/compareArraysByProp';
+import getLocalTimeInfo from './helpers/getLocalTimeInfo';
+import genCommaList from './helpers/genCommaList';
+import validateEmail from './helpers/validators/validateEmail';
+import validatePhoneNumber from './helpers/validators/validatePhoneNumber';
+import validateString from './helpers/validators/validateString';
+import idify from './helpers/idify';
+import prefixWithAOrAn from './helpers/prefixWithAOrAn';
+import everyAsync from './helpers/asyncArrayFunctions/everyAsync';
+import filterAsync from './helpers/asyncArrayFunctions/filterAsync';
+import forEachAsync from './helpers/asyncArrayFunctions/forEachAsync';
+import mapAsync from './helpers/asyncArrayFunctions/mapAsync';
+import someAsync from './helpers/asyncArrayFunctions/someAsync';
+import capitalize from './helpers/capitalize';
+import shuffleArray from './helpers/shuffleArray';
+import getWordCount from './helpers/getWordCount';
+import cloneDeep from './helpers/cloneDeep';
+import getTimestampFromTimeInfoInET from './helpers/getTimestampFromTimeInfoInET';
+
+// Import types
+import ParamType from './types/ParamType';
+import DayOfWeek from './types/DayOfWeek';
+import Log from './types/Log';
+import LogType from './types/LogType';
+import LogSource from './types/LogSource';
+import LogAction from './types/LogAction';
+import LogBuiltInMetadata from './types/LogBuiltInMetadata';
+import LogMetadataType from './types/LogMetadataType';
+import LogFunction from './types/LogFunction';
+import LogTypeSpecificInfo from './types/Log/LogTypeSpecificInfo';
+import LogMainInfo from './types/Log/LogMainInfo';
+import LogSourceSpecificInfo from './types/Log/LogSourceSpecificInfo';
+import LogLevel from './types/LogLevel';
+import CommonKitErrorCode from './types/CommonKitErrorCode';
+
+// Export each item
+export {
+  // Errors
+  ErrorWithCode,
+  // Constants
+  MINUTE_IN_MS,
+  HOUR_IN_MS,
+  DAY_IN_MS,
+  LOG_REVIEW_ROUTE_PATH_PREFIX,
+  LOG_ROUTE_PATH,
+  LOG_REVIEW_STATUS_ROUTE,
+  LOG_REVIEW_GET_LOGS_ROUTE,
+  SELECT_ADMIN_CHECK_ROUTE,
+  // Types
+  CommonKitErrorCode,
+  ParamType,
+  DayOfWeek,
+  Log,
+  LogType,
+  LogSource,
+  LogAction,
+  LogBuiltInMetadata,
+  LogMetadataType,
+  LogFunction,
+  LogTypeSpecificInfo,
+  LogMainInfo,
+  LogSourceSpecificInfo,
+  LogLevel,
+  // Helpers
+  abbreviate,
+  avg,
+  ceilToNumDecimals,
+  floorToNumDecimals,
+  forceNumIntoBounds,
+  padDecimalZeros,
+  padZerosLeft,
+  roundToNumDecimals,
+  sum,
+  waitMs,
+  getOrdinal,
+  getTimeInfoInET,
+  startMinWait,
+  getHumanReadableDate,
+  getPartOfDay,
+  stringsToHumanReadableList,
+  onlyKeepLetters,
+  parallelLimit,
+  getMonthName,
+  genCSV,
+  extractProp,
+  compareArraysByProp,
+  genCommaList,
+  validateEmail,
+  validatePhoneNumber,
+  validateString,
+  getLocalTimeInfo,
+  idify,
+  prefixWithAOrAn,
+  everyAsync,
+  filterAsync,
+  forEachAsync,
+  mapAsync,
+  someAsync,
+  capitalize,
+  shuffleArray,
+  getWordCount,
+  cloneDeep,
+  getTimestampFromTimeInfoInET,
+};

package/src/types/CommonKitErrorCode.ts

@@ -0,0 +1,13 @@
+// Highest error code = DCK3
+
+/**
+ * List of error codes built into the common kit
+ * @author Gabe Abrams
+ */
+enum CommonKitErrorCode {
+  SimpleDateChooserInvalidDateRange = 'DCK1',
+  SimpleDateChooserInvalidNumMonths = 'DCK2',
+  ETTimestampInvalid = 'DCK3',
+}
+
+export default CommonKitErrorCode;

package/src/types/DayOfWeek.ts

@@ -0,0 +1,15 @@
+/**
+ * Days of the week
+ * @author Gabe Abrams
+ */
+enum DayOfWeek {
+  Monday = 'm',
+  Tuesday = 't',
+  Wednesday = 'w',
+  Thursday = 'r',
+  Friday = 'f',
+  Saturday = 's',
+  Sunday = 'u',
+}
+
+export default DayOfWeek;

package/src/types/Log/LogMainInfo.ts

@@ -0,0 +1,69 @@
+// Import shared types
+import LogLevel from '../LogLevel';
+
+/**
+ * Main information in a log event
+ * @author Gabe Abrams
+ */
+type LogMainInfo = {
+  // Unique id of the log event
+  id: string,
+  // First name of the user
+  userFirstName: string,
+  // Last name of the user
+  userLastName: string,
+  // User email
+  userEmail: string,
+  // User Canvas Id
+  userId: number,
+  // If true, the user is a learner
+  isLearner: boolean,
+  // If true, the user is an admin
+  isAdmin: boolean,
+  // If true, the user is a ttm
+  isTTM: boolean,
+  // The id of the Canvas course that the user launched from
+  courseId: number,
+  // The name of the Canvas course
+  courseName: string,
+  // Browser info
+  browser: {
+    // Name of the browser
+    name: string,
+    // Version of the browser
+    version: string,
+  },
+  // Device info
+  device: {
+    // Name of the operating system
+    os: string,
+    // If true, device is a mobile device
+    isMobile: boolean,
+  },
+  // Calendar year that the event is from
+  year: number,
+  // Month that the event is from (1 = Jan, 12 = Dec)
+  month: number,
+  // Day of the month that the event is from
+  day: number,
+  // Hour of the day (24hr) when the event occurred
+  hour: number,
+  // Minute of the day when the event occurred
+  minute: number,
+  // Timestamp of event (ms since epoch)
+  timestamp: number,
+  // Context of the event (each app determines how to organize contexts)
+  context: string,
+  // Subcontext of the event (each app determines how to organize subcontexts)
+  subcontext: string,
+  // List of tags that apply to this action (each app determines tag usage)
+  tags: string[],
+  // Log level
+  level: LogLevel,
+  // Additional optional custom metadata
+  metadata?: {
+    [k: string]: any,
+  },
+};
+
+export default LogMainInfo;

package/src/types/Log/LogSourceSpecificInfo.ts

@@ -0,0 +1,25 @@
+// Import shared types
+import LogSource from '../LogSource';
+
+/**
+ * Log info that is specific to the type of source
+ * @author Gabe Abrams
+ */
+type LogSourceSpecificInfo = (
+  // Client
+  | {
+    // Source of the event
+    source: LogSource.Client,
+  }
+  // Server
+  | {
+    // Source of the event
+    source: LogSource.Server,
+    // Route path (e.g. /api/admin/courses/53450/blocks)
+    routePath: string,
+    // Route template (e.g. /api/admin/courses/:courseId/blocks)
+    routeTemplate: string,
+  }
+);
+
+export default LogSourceSpecificInfo;

package/src/types/Log/LogTypeSpecificInfo.ts

@@ -0,0 +1,33 @@
+// Import shared types
+import LogAction from '../LogAction';
+import LogType from '../LogType';
+
+/**
+ * Log info that is specific to the type of log
+ * @author Gabe Abrams
+ */
+type LogTypeSpecificInfo = (
+  // Error
+  | {
+    // Type of the event
+    type: LogType.Error,
+    // The error message
+    errorMessage: string,
+    // The error code
+    errorCode: string,
+    // Error stack trace
+    errorStack: string,
+  }
+  // Action
+  | {
+    // Type of the event
+    type: LogType.Action,
+    // Target of the action (each app determines the list of targets)
+    // These are usually buttons, panels, elements, etc.
+    target: string,
+    // The type of action performed on the target
+    action: LogAction,
+  }
+);
+
+export default LogTypeSpecificInfo;

package/src/types/Log/index.ts

@@ -0,0 +1,17 @@
+// Import shared types
+import LogMainInfo from './LogMainInfo';
+import LogSourceSpecificInfo from './LogSourceSpecificInfo';
+import LogTypeSpecificInfo from './LogTypeSpecificInfo';
+
+/**
+ * A single log event corresponding to an action performed by a user or an
+ *   error encountered by a user
+ * @author Gabe Abrams
+ */
+type Log = (
+  LogMainInfo
+  & LogSourceSpecificInfo
+  & LogTypeSpecificInfo
+);
+
+export default Log;