dce-commonkit 4.4.0

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

@@ -0,0 +1,83 @@
+// Import the function to be tested
+// import findURLs from './findURL';
+
+// // Import constants
+// import { INVALID_STRING_ERRORS, INVALID_REGEX_ERROR } from './shared/constants/ERROR_MESSAGES';
+
+// /*------------------------------------------------------------------------*/
+// /* ---------------------------- Valid Tests --------------------------- */
+// /*------------------------------------------------------------------------*/
+
+// const validTests: { block: string, expected: { start: number, end: number }[] }[] = [
+//   {
+//     block: 'Visit http://example.com for more information.',
+//     expected: [{ start: 6, end: 23 }],
+//   },
+//   {
+//     block: 'Multiple URLs: http://one.com and http://two.com.',
+//     expected: [
+//       { start: 15, end: 29 },
+//       { start: 34, end: 48 },
+//     ],
+//   },
+//   {
+//     block: 'Localhost URLs: http://localhost and http://127.0.0.1.',
+//     expected: [
+//       { start: 16, end: 31 },
+//       { start: 36, end: 52 },
+//     ],
+//   },
+//   {
+//     block: 'Embedded URL: text https://embedded-url.com?query=1&value=2.',
+//     expected: [{ start: 13, end: 51 }],
+//   },
+//   {
+//     block: 'Secure site: https://secure-site.com/path?query=string#fragment',
+//     expected: [{ start: 13, end: 58 }],
+//   },
+// ];
+
+// test(
+//   'Returns correct start and end indices for valid URLs within a string.',
+//   async () => {
+//     validTests.forEach(({ block, expected }) => {
+//       expect(findURLs(block)).toStrictEqual(expected);
+//     });
+//   },
+// );
+
+// /*------------------------------------------------------------------------*/
+// /* ---------------------------- Invalid Tests --------------------------- */
+// /*------------------------------------------------------------------------*/
+
+// const invalidTests: { block: string, expected: { start: number, end: number }[] }[] = [
+//   {
+//     block: 'No URL.',
+//     expected: [],
+//   },
+//   {
+//     block: 'URL format is wrong: http:/example.com and htt://example.com.',
+//     expected: [],
+//   },
+//   {
+//     block: 'Any punctuation after the URL http://example.com, should not count.',
+//     expected: [{ start: 20, end: 37 }],
+//   },
+//   {
+//     block: 'Starting punctuation ,http://example.com should not count.',
+//     expected: [{ start: 22, end: 39 }],
+//   },
+//   {
+//     block: 'Spaces in the middle http://exa mple.com is invalid.',
+//     expected: [],
+//   },
+// ];
+
+// test(
+//   'Returns empty array for strings without valid URLs.',
+//   async () => {
+//     invalidTests.forEach(({ block, expected }) => {
+//       expect(findURLs(block)).toStrictEqual(expected);
+//     });
+//   },
+// );

package/src/helpers/validators/findURL.ts

@@ -0,0 +1,43 @@
+// /**
+//  * This function finds URLs within a given string and returns an array of 
+//  * their locations.
+//  * @author Leisha Bhandari
+//  * @param block: The block of text to search for URLs
+//  * @returns Arrays where each of them contain the start and end index of the URL
+//  */
+// function findURLs(block: string): { start: number, end: number }[] {
+//   // Expression representing the skeleton of a URL to help match and find the  
+//   // URLs within the block of text (Also takes care of Unicode characters)
+//   const urlSkeleton = /(https?:\/\/[^\s\u0000-\u001F.,]+[^\s\u0000-\u001F.,]?(?:\?[^\s\u0000-\u001F]+)?(?:#[^\s\u0000-\u001F]+)?)/g;
+//   const found: { start: number, end: number }[] = [];
+//   let match: RegExpExecArray | null;
+
+//   // While loop to find the URLs in the given block of texts using the URL 
+//   // skeleton
+//   while ((match === urlSkeleton.exec(block)) 
+//          && match !== null) {
+//     // To find the beginning index of the URL
+//     let start = match.index;
+//     // To find the last index of the URL
+//     let end = match.index + match[0].length;
+
+//     // If statements to check whether the URL is followed by some kind of 
+//     // punctuation mark
+//     if (block.charAt(end) === '.' || /[,;:!?"]/.test(block.charAt(end))) {
+//       end--;
+//     }
+
+//     // While statement to make sure that the URL does not start with a 
+//     // punctuation mark
+//     while (start > 0 && /[.,:;!?]/.test(block.charAt(start - 1))) {
+//       start--;
+//     }
+
+//     // The object with start and end index of the URL is found and pushed to 
+//     // the found array
+//     found.push({ start, end });
+//   }
+  
+//   // Returns the array of the found URLs location
+//   return found;
+// }

package/src/helpers/validators/shared/constants/ERROR_MESSAGES.ts

@@ -0,0 +1,18 @@
+/*------------------------------------------------------------------------*/
+/* ------------------------------ Constants ----------------------------- */
+/*------------------------------------------------------------------------*/
+
+export const INVALID_REGEX_ERROR = 'input does not follow the requested format';
+export const INVALID_EMAIL_ERROR = 'Please provide a valid email address.';
+export const INVALID_PHONE_ERROR = 'Please provide a valid phone number.';
+export const INVALID_STRING_ERRORS = {
+  MIN_LEN: (minLen: number) => {
+    return `input must not be under ${minLen} character(s)`;
+  },
+  MAX_LEN: (maxLen: number) => {
+    return `input must not be over ${maxLen} character(s)`;
+  },
+  LETTERS_ONLY: 'input must only contain letters',
+  NUMBERS_ONLY: 'input must only contain numbers',
+  MESSAGE_INTRO: 'The following error(s) occurred: ',
+};

package/src/helpers/validators/shared/helpers/validateRegex.ts

@@ -0,0 +1,47 @@
+// Import types
+import ValidationResult from '../types/ValidationResult';
+
+// Import constants
+import { INVALID_REGEX_ERROR } from '../constants/ERROR_MESSAGES';
+
+/**
+ * Determines whether a given input string is considered valid based on
+ *   the provided regex.
+ * @author Austen Money
+ * @param opts object containing all args
+ * @param opts.input user-provided input to validate
+ * @param opts.regex regular expression to check against input
+ * @param [opts.regexDescription] description of what regexString is checking
+ *   for, used to customize error message
+ * @returns the unchanged input if valid, or a customized error message if
+ *   invalid
+ */
+const validateRegex = (
+  opts: {
+    input: string,
+    regex: RegExp,
+    regexDescription?: string,
+  },
+): ValidationResult<string> => {
+  // customize error message in case of invalid input
+  const errorMessage = `${INVALID_REGEX_ERROR}${
+    opts.regexDescription
+      ? ': '
+      : ''
+  }${opts.regexDescription}`;
+
+  // return error message if test is invalid, or input string if valid
+  return (
+    opts.regex.test(opts.input)
+      ? {
+        isValid: true,
+        cleanedValue: opts.input,
+      }
+      : {
+        isValid: false,
+        errorMessage,
+      }
+  );
+};
+
+export default validateRegex;

package/src/helpers/validators/shared/types/ValidationResult.ts

@@ -0,0 +1,20 @@
+/**
+ * Result of a validation function.
+ * @author Austen Money
+ */
+type ValidationResult<CleanedValueType> = (
+  | {
+    // if true, the validation was successful
+    isValid: true,
+    // the cleaned version of the value
+    cleanedValue: CleanedValueType,
+  }
+  | {
+    // if false, the validation was not successful
+    isValid: false,
+    // describes why the validation failed
+    errorMessage: string,
+  }
+);
+
+export default ValidationResult;

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

@@ -0,0 +1,90 @@
+
+// Import the function to be tested
+// import isValid from './validURL';
+
+// // Import constants
+// import { INVALID_STRING_ERRORS, INVALID_REGEX_ERROR } from './shared/constants/ERROR_MESSAGES';
+
+// /*------------------------------------------------------------------------*/
+// /* ---------------------------- Valid Tests --------------------------- */
+// /*------------------------------------------------------------------------*/
+
+// const validUrls: string[] = [
+//   'http://example.com',
+//   'https://example.com',
+//   'http://www.example.com',
+//   'https://www.example.com',
+//   'https://example.com/path',
+//   'http://example.com/path',
+//   'https://example.com?query=string',
+//   'http://example.com?query=string',
+//   'https://example.com#fragment',
+//   'http://example.com#fragment',
+//   'http://localhost',
+//   'https://localhost:3000',
+//   'http://localhost:3000',
+//   'http://127.0.0.1',
+//   'http://127.0.0.1:3000',
+//   'ftp://example.com/path',
+//   'ftp://example.com',
+//   'https://127.0.0.1:3000',
+//   'file:///C:/path/to/file'
+// ];
+
+// test(
+//   'Returns true for a given valid URL.',
+//   async () => {
+//     validUrls.forEach((url) => {
+//       expect(isValid(url)).toBe(true);
+//     });
+//   },
+// );
+
+// /*------------------------------------------------------------------------*/
+// /* ---------------------------- Invalid Tests --------------------------- */
+// /*------------------------------------------------------------------------*/
+
+// const invalidUrls: string[] = [
+//   '',
+//   ' ',
+//   'example',
+//   'http://',
+//   'http://.',
+//   'http://..',
+//   'http://##/',
+//   'http://../',
+//   'http://??/',
+//   'http://#',
+//   'http://##',
+//   '//',
+//   '//a',
+//   '///a',
+//   '///',
+//   'http:///a',
+//   'http://www.foo.bar./',
+//   'http://foo.bar/foo(bar)baz quux',
+//   'http://3628126748',
+//   'http://.www.foo.bar/',
+//   'http://.www.foo.bar./',
+//   'http://123.123.123',
+//   'http://1.1.1.1.1',
+//   'http://example.com:99999',
+//   'http://example.com:80:80',
+//   'http://example.com::80',
+//   'http://example.com:-80',
+//   'http://-example.com',
+//   'http://example.com-',
+//   'http://example.com_',
+//   'http://example..com',
+//   'http://example.com.',
+//   'http://.example.com'
+// ];
+
+// test(
+//   'Returns false for a given invalid URL.',
+//   async () => {
+//     invalidUrls.forEach((url) => {
+//       expect(isValid(url)).toBe(false);
+//     });
+//   },
+// );

package/src/helpers/validators/validURL.ts

@@ -0,0 +1,18 @@
+/**
+ * This function checks if a given input string is a valid URL.
+ * @author Leisha Bhandari
+ * @param URL: The input string that needs checked as a URL or not.
+ * @returns A true boolean value if the input string is a valid URL, and a false
+ *          boolean value if the input string is a invalid URL
+ */
+function isValid(url: string): boolean {
+  // Uses the input URL to create a URL object
+  try {
+    new URL(url);
+    // URL constructor does not throw an error, so input URL is valid
+    return true;
+  } catch (err) {
+    // URL constructor throws an error, so input URL is invalid
+    return false;
+  }
+}

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

@@ -0,0 +1,110 @@
+// Import types
+import ValidationResult from './shared/types/ValidationResult';
+
+// Import constants
+import { INVALID_EMAIL_ERROR } from './shared/constants/ERROR_MESSAGES';
+
+// Import function
+import validateEmail from './validateEmail';
+
+/*------------------------------------------------------------------------*/
+/* ---------------------------- Valid Tests --------------------------- */
+/*------------------------------------------------------------------------*/
+
+const validEmailPairs: { input: string, cleaned: string }[] = [
+  {
+    input: 'username@gmail.com',
+    cleaned: 'username@gmail.com',
+  },
+  {
+    input: 'u@hotmail.org',
+    cleaned: 'u@hotmail.org',
+  },
+  {
+    input: '   username@gmail.com',
+    cleaned: 'username@gmail.com',
+  },
+  {
+    input: 'username@gmail.com        ',
+    cleaned: 'username@gmail.com',
+  },
+  {
+    input: ' username@gmail.com ',
+    cleaned: 'username@gmail.com',
+  },
+  {
+    input: 'username@harvard.edu',
+    cleaned: 'username@harvard.edu',
+  },
+  {
+    input: 'username@harvard.subdomain.edu',
+    cleaned: 'username@harvard.subdomain.edu',
+  },
+  {
+    input: '\nusername@harvard.subdomain.edu',
+    cleaned: 'username@harvard.subdomain.edu',
+  },
+  {
+    input: '\n\tusername@harvard.subdomain.edu',
+    cleaned: 'username@harvard.subdomain.edu',
+  },
+  {
+    input: 'username@harvard.subdomain.edu\n',
+    cleaned: 'username@harvard.subdomain.edu',
+  },
+  {
+    input: 'username@harvard.subdomain.edu\n\t',
+    cleaned: 'username@harvard.subdomain.edu',
+  },
+];
+
+test(
+  'Returns true for a given valid email and removes any leading or trailing whitespace.',
+  async () => {
+    validEmailPairs.forEach((pair) => {
+      const validResponse: ValidationResult<string> = {
+        isValid: true,
+        cleanedValue: pair.cleaned,
+      };
+
+      expect(validateEmail(pair.input)).toStrictEqual(validResponse);
+    });
+  },
+);
+
+/*------------------------------------------------------------------------*/
+/* ---------------------------- Invalid Tests --------------------------- */
+/*------------------------------------------------------------------------*/
+
+const invalidEmails: string[] = [
+  '',
+  ' ',
+  'gmail.com',
+  '@gmail.com ',
+  'username',
+  'username@.com',
+  'user name@gmail.com',
+  'username @gmail.com',
+  'username@ gmail.com',
+  'username@gmail .com',
+  'username\t@gmail.com',
+  'username\n@gmail.com',
+  'username@gmail\n.com',
+  'username@gmail.\tcom',
+  'user\nname@gmail.com',
+  'user\tname@gmail.com',
+];
+
+const invalidResponse: ValidationResult<string> = {
+  isValid: false,
+  errorMessage: INVALID_EMAIL_ERROR,
+};
+
+test(
+  'Returns false for a given invalid email.',
+  async () => {
+    invalidEmails.forEach((email) => {
+      expect(validateEmail(email)).toStrictEqual(invalidResponse);
+    });
+  },
+);

package/src/helpers/validators/validateEmail.ts

@@ -0,0 +1,47 @@
+// Import helpers
+import validateRegex from './shared/helpers/validateRegex';
+
+// Import constants
+import { INVALID_EMAIL_ERROR } from './shared/constants/ERROR_MESSAGES';
+
+// Import types
+import ValidationResult from './shared/types/ValidationResult';
+
+/**
+ * Determines whether a given email address is valid.
+ * @author Austen Money
+ * @param email email address to validate
+ * @returns whether email fulfills proper formatting requirements, includes a
+ *   cleaned version of the address without leading or trailing
+ *   whitespace if valid or an error message if invalid.
+ */
+const validateEmail = (
+  email: string,
+): ValidationResult<string> => {
+  // validation regex, sourced from HTML living standard: http://www.whatwg.org/specs/web-apps/current-work/multipage/forms.html#e-mail-state-(type=email)
+  // eslint-disable-next-line max-len
+  const emailRegex = /^[a-zA-Z0-9.!#$%&'*+\/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/;
+
+  // remove leading and trailing whitespace
+  const cleanedValue: string = email.replace(/^\s+|\s+$/g, '');
+
+  // validate email with regex, and return error if not valid
+  return (
+    validateRegex(
+      {
+        input: cleanedValue,
+        regex: emailRegex,
+      },
+    ).isValid
+      ? {
+        isValid: true,
+        cleanedValue,
+      }
+      : {
+        isValid: false,
+        errorMessage: INVALID_EMAIL_ERROR,
+      }
+  );
+};
+
+export default validateEmail;

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

@@ -0,0 +1,94 @@
+// Import types
+import ValidationResult from './shared/types/ValidationResult';
+
+// Import constants
+import { INVALID_PHONE_ERROR } from './shared/constants/ERROR_MESSAGES';
+
+// Import function
+import validatePhoneNumber from './validatePhoneNumber';
+
+/*------------------------------------------------------------------------*/
+/* ---------------------------- Valid Tests --------------------------- */
+/*------------------------------------------------------------------------*/
+
+const cleanedNumber = '1234567890';
+const cleanedNumberExt = '11234567890';
+
+const validPhoneNumbers: { input: string, cleaned: string }[] = [
+  {
+    input: '1234567890',
+    cleaned: cleanedNumber,
+  },
+  {
+    input: '(123)-456-7890',
+    cleaned: cleanedNumber,
+  },
+  {
+    input: '123-456-7890',
+    cleaned: cleanedNumber,
+  },
+  {
+    input: '(123)456-7890',
+    cleaned: cleanedNumber,
+  },
+  {
+    input: '(123)4567890',
+    cleaned: cleanedNumber,
+  },
+  {
+    input: '    123456-7890 ',
+    cleaned: cleanedNumber,
+  },
+  {
+    input: '+1 123 456 7890',
+    cleaned: cleanedNumberExt,
+  },
+  {
+    input: '+1123456 7890',
+    cleaned: cleanedNumberExt,
+  },
+  {
+    input: '+1(123)456-7890',
+    cleaned: cleanedNumberExt,
+  },
+];
+
+test(
+  'Returns true for a given valid phone number and removes any non-digit characters.',
+  async () => {
+    validPhoneNumbers.forEach((pair) => {
+      const validResponse: ValidationResult<string> = {
+        isValid: true,
+        cleanedValue: pair.cleaned,
+      };
+
+      expect(validatePhoneNumber(pair.input)).toStrictEqual(validResponse);
+    });
+  },
+);
+
+/*------------------------------------------------------------------------*/
+/* ---------------------------- Invalid Tests --------------------------- */
+/*------------------------------------------------------------------------*/
+
+const invalidPhoneNumbers: string[] = [
+  '123456789',
+  '1234567894567890',
+  '1234-567-890',
+  '123456m78',
+  '123 4567 890',
+];
+
+const invalidResponse: ValidationResult<string> = {
+  isValid: false,
+  errorMessage: INVALID_PHONE_ERROR,
+};
+
+test(
+  'Returns false for a given valid phone number.',
+  async () => {
+    invalidPhoneNumbers.forEach((phoneNumber) => {
+      expect(validatePhoneNumber(phoneNumber)).toStrictEqual(invalidResponse);
+    });
+  },
+);

package/src/helpers/validators/validatePhoneNumber.ts

@@ -0,0 +1,49 @@
+// Import helpers
+import validateRegex from './shared/helpers/validateRegex';
+
+// Import constants
+import { INVALID_PHONE_ERROR } from './shared/constants/ERROR_MESSAGES';
+
+// Import types
+import ValidationResult from './shared/types/ValidationResult';
+
+/**
+ * Determines whether a given phone number is valid.
+ * @author Austen Money
+ * @param phoneNumber phone number to validate
+ * @returns whether phone number is considered valid - if valid, also returns
+ *   a cleaned version of the number without any formatting. If invalid,
+ *   returns an error message.
+ */
+const validatePhoneNumber = (
+  phoneNumber: string,
+): ValidationResult<string> => {
+  // regex to validate phone number
+  const validationRegex = /^\s*(?:\+?(\d{1,3}))?[-. (]*(\d{3})[-. )]*(\d{3})[-. ]*(\d{4})(?: *x(\d+))?\s*$/;
+
+  // validate phone number with regex
+  const validationResponse = validateRegex(
+    {
+      input: phoneNumber,
+      regex: validationRegex,
+    },
+  );
+
+  // remove all non-digits from number
+  const cleanedValue: string = phoneNumber.replace(/\D/g, '');
+
+  // return cleaned value if valid, or error message if invalid
+  return (
+    validationResponse.isValid
+      ? {
+        isValid: true,
+        cleanedValue,
+      }
+      : {
+        isValid: false,
+        errorMessage: INVALID_PHONE_ERROR,
+      }
+  );
+};
+
+export default validatePhoneNumber;