dce-commonkit 4.4.0

package/lib/types/LogType.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Type of a log event
+ * @author Gabe Abrams
+ */
+declare enum LogType {
+    Action = "action",
+    Error = "error"
+}
+export default LogType;

package/lib/types/LogType.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Type of a log event
+ * @author Gabe Abrams
+ */
+var LogType;
+(function (LogType) {
+    // User action
+    LogType["Action"] = "action";
+    // Error
+    LogType["Error"] = "error";
+})(LogType || (LogType = {}));
+exports.default = LogType;
+//# sourceMappingURL=LogType.js.map

package/lib/types/LogType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LogType.js","sourceRoot":"","sources":["../../src/types/LogType.ts"],"names":[],"mappings":";;AAAA;;;GAGG;AACH,IAAK,OAKJ;AALD,WAAK,OAAO;IACV,cAAc;IACd,4BAAiB,CAAA;IACjB,QAAQ;IACR,0BAAe,CAAA;AACjB,CAAC,EALI,OAAO,KAAP,OAAO,QAKX;AAED,kBAAe,OAAO,CAAC"}

package/lib/types/ParamType.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Server-side API param types
+ * @author Gabe Abrams
+ */
+declare enum ParamType {
+    Boolean = "Boolean",// Boolean
+    BooleanOptional = "BooleanOptional",// Optional boolean
+    Float = "Float",// Float Number
+    FloatOptional = "FloatOptional",// Optional Float Number
+    Int = "Int",// Integer Number
+    IntOptional = "IntOptional",// Optional Integer Number
+    JSON = "JSON",// JSONified object
+    JSONOptional = "JSONOptional",// Optional JSONified object
+    String = "String",// String
+    StringOptional = "StringOptional"
+}
+export default ParamType;

package/lib/types/ParamType.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Server-side API param types
+ * @author Gabe Abrams
+ */
+var ParamType;
+(function (ParamType) {
+    ParamType["Boolean"] = "Boolean";
+    ParamType["BooleanOptional"] = "BooleanOptional";
+    ParamType["Float"] = "Float";
+    ParamType["FloatOptional"] = "FloatOptional";
+    ParamType["Int"] = "Int";
+    ParamType["IntOptional"] = "IntOptional";
+    ParamType["JSON"] = "JSON";
+    ParamType["JSONOptional"] = "JSONOptional";
+    ParamType["String"] = "String";
+    ParamType["StringOptional"] = "StringOptional";
+})(ParamType || (ParamType = {}));
+exports.default = ParamType;
+//# sourceMappingURL=ParamType.js.map

package/lib/types/ParamType.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ParamType.js","sourceRoot":"","sources":["../../src/types/ParamType.ts"],"names":[],"mappings":";;AAAA;;;GAGG;AACH,IAAK,SAWJ;AAXD,WAAK,SAAS;IACZ,gCAAmB,CAAA;IACnB,gDAAmC,CAAA;IACnC,4BAAe,CAAA;IACf,4CAA+B,CAAA;IAC/B,wBAAW,CAAA;IACX,wCAA2B,CAAA;IAC3B,0BAAa,CAAA;IACb,0CAA6B,CAAA;IAC7B,8BAAiB,CAAA;IACjB,8CAAiC,CAAA;AACnC,CAAC,EAXI,SAAS,KAAT,SAAS,QAWb;AAED,kBAAe,SAAS,CAAC"}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "dce-commonkit",
+  "version": "4.4.0",
+  "description": "Common helpers, constants, and other resources that are shared between dce-reactkit and dce-expresskit",
+  "keywords": [
+    "DCE",
+    "Harvard",
+    "React",
+    "Express",
+    "Helpers"
+  ],
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "homepage": "https://github.com/harvard-edtech/dce-commonkit#readme",
+  "bugs": {
+    "url": "https://github.com/harvard-edtech/dce-commonkit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harvard-edtech/dce-commonkit.git"
+  },
+  "license": "MIT",
+  "author": "Gabe Abrams <gabeabrams@gmail.com>",
+  "type": "commonjs",
+  "scripts": {
+    "build": "tsc --project ./tsconfig.json"
+  },
+  "jest": {
+    "preset": "ts-jest",
+    "testEnvironment": "jsdom"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/express-session": "^1.18.1",
+    "@types/node": "^24.10.1",
+    "@typescript-eslint/eslint-plugin": "^5.59.9",
+    "@typescript-eslint/parser": "^5.59.9",
+    "eslint": "^8.42.0",
+    "typescript": "^5.8.2",
+    "@types/jest": "^28.1.7",
+    "jest": "^28.1.3",
+    "ts-jest": "^28.0.8"
+  },
+  "dependencies": {
+    "nanoclone": "^1.0.2"
+  }
+}

package/src/constants/DAY_IN_MS.ts

@@ -0,0 +1,7 @@
+/**
+ * One day in ms
+ * @author Gabe Abrams
+ */
+const DAY_IN_MS = 86400000;
+
+export default DAY_IN_MS;

package/src/constants/HOUR_IN_MS.ts

@@ -0,0 +1,7 @@
+/**
+ * One hour in ms
+ * @author Gabe Abrams
+ */
+const HOUR_IN_MS = 3600000;
+
+export default HOUR_IN_MS;

package/src/constants/LOG_REVIEW_GET_LOGS_ROUTE.ts

@@ -0,0 +1,9 @@
+import ROUTE_PATH_PREFIX from './ROUTE_PATH_PREFIX';
+
+/**
+ * Path of the route for getting logs for log review
+ * @author Gabe Abrams
+ */
+const LOG_REVIEW_GET_LOGS_ROUTE = `/admin${ROUTE_PATH_PREFIX}/logs`;
+
+export default LOG_REVIEW_GET_LOGS_ROUTE;

package/src/constants/LOG_REVIEW_ROUTE_PATH_PREFIX.ts

@@ -0,0 +1,9 @@
+import ROUTE_PATH_PREFIX from './ROUTE_PATH_PREFIX';
+
+/**
+ * Path of the route for storing client-side logs
+ * @author Gabe Abrams
+ */
+const LOG_REVIEW_ROUTE_PATH_PREFIX = `/admin${ROUTE_PATH_PREFIX}/logs`;
+
+export default LOG_REVIEW_ROUTE_PATH_PREFIX;

package/src/constants/LOG_REVIEW_STATUS_ROUTE.ts

@@ -0,0 +1,10 @@
+import ROUTE_PATH_PREFIX from './ROUTE_PATH_PREFIX';
+
+/**
+ * Route for checking the status of the current user's
+ *   access to log review
+ * @author Gabe Abrams
+ */
+const LOG_REVIEW_STATUS_ROUTE = `${ROUTE_PATH_PREFIX}/logs/access_allowed`;
+
+export default LOG_REVIEW_STATUS_ROUTE;

package/src/constants/LOG_ROUTE_PATH.ts

@@ -0,0 +1,9 @@
+import ROUTE_PATH_PREFIX from './ROUTE_PATH_PREFIX';
+
+/**
+ * Path of the route for storing client-side logs
+ * @author Gabe Abrams
+ */
+const LOG_ROUTE_PATH = `${ROUTE_PATH_PREFIX}/log`;
+
+export default LOG_ROUTE_PATH;

package/src/constants/MINUTE_IN_MS.ts

@@ -0,0 +1,7 @@
+/**
+ * One minute in ms
+ * @author Gabe Abrams
+ */
+const MINUTE_IN_MS = 60000;
+
+export default MINUTE_IN_MS;

package/src/constants/ROUTE_PATH_PREFIX.ts

@@ -0,0 +1,7 @@
+/**
+ * Path that all routes start with
+ * @author Gabe Abrams
+ */
+const ROUTE_PATH_PREFIX = '/dce-reactkit';
+
+export default ROUTE_PATH_PREFIX;

package/src/constants/SELECT_ADMIN_CHECK_ROUTE.ts

@@ -0,0 +1,7 @@
+/**
+ * Route for checking if the current user is a select admin
+ * @author Gabe Abrams
+ */
+const SELECT_ADMIN_CHECK_ROUTE = '/api/admin/select/is-select-admin';
+
+export default SELECT_ADMIN_CHECK_ROUTE;

package/src/errors/ErrorWithCode.ts

@@ -0,0 +1,15 @@
+/**
+ * An error with a code
+ * @author Gabe Abrams
+ */
+class ErrorWithCode extends Error {
+  code: string;
+
+  constructor(message: string, code: string) {
+    super(message);
+    this.name = 'ErrorWithCode';
+    this.code = code;
+  }
+}
+
+export default ErrorWithCode;

package/src/helpers/abbreviate.test.ts

@@ -0,0 +1,26 @@
+/**
+ * Unit tests for abbreviate helper
+ * @author Gabe Abrams
+ */
+
+import abbreviate from './abbreviate';
+
+describe('helpers > abbreviate', () => {
+  it('should return the original text if it is shorter than the maxChars parameter', () => {
+      const text = 'Hello, world!';
+      const maxChars = 20;
+      expect(abbreviate(text, maxChars)).toEqual(text);
+  });
+
+  it('should abbreviate the text if it is longer than the maxChars parameter', () => {
+    const text = 'This is a really long string that needs to be abbreviated';
+    const maxChars = 20;
+    expect(abbreviate(text, maxChars)).toEqual('This is a really...');
+  });
+
+  it('should handle leading/trailing whitespace', () => {
+    const text = '   This is a string with leading/trailing whitespace   ';
+    const maxChars = 20;
+    expect(abbreviate(text, maxChars)).toEqual('This is a string...');
+  });
+});

package/src/helpers/abbreviate.ts

@@ -0,0 +1,25 @@
+/**
+ * Shorten text so it fits into a certain number of chars
+ * @author Gabe Abrams
+ * @param text the text to abbreviate
+ * @param maxChars the maximum number of chars to include
+ * @returns abbreviated text with length no greater than maxChars
+ *   (including ellipses if applicable)
+ */
+const abbreviate = (text: string, maxChars: number): string => {
+  // Check if already short enough
+  if (text.trim().length < maxChars) {
+    return text.trim();
+  }
+
+  // Abbreviate
+  const shortenedText = (
+    text
+      .trim()
+      .substring(0, maxChars - 3)
+      .trim()
+  );
+  return `${shortenedText}...`;
+};
+
+export default abbreviate;

package/src/helpers/asyncArrayFunctions/everyAsync.test.ts

@@ -0,0 +1,114 @@
+// Import item to test
+import everyAsync from './everyAsync';
+
+describe('everyAsync', () => {
+  it('returns true for an empty array', async () => {
+    const result = await everyAsync(
+      [],
+      async () => {
+        return true;
+      },
+    );
+    expect(result).toBe(true);
+  });
+
+  it('returns true if the operator function returns true for every item in the array', async () => {
+    const result = await everyAsync(
+      [1, 2, 3],
+      async (item) => {
+        return item > 0;
+      },
+    );
+    expect(result).toBe(true);
+  });
+
+  it('returns false if the operator function returns false for any item in the array', async () => {
+    const result = await everyAsync(
+      [1, 2, 3],
+      async (item) => {
+        return item > 1;
+      },
+    );
+    expect(result).toBe(false);
+  });
+
+  it('passes the index as the second argument to the operator function', async () => {
+    const result = await everyAsync(
+      [1, 2, 3],
+      async (item, index) => {
+        return index === item - 1;
+      },
+    );
+    expect(result).toBe(true);
+  });
+
+  it('passes an object with a breakNow function and the array as the third argument to the operator function', async () => {
+    const result = await everyAsync(
+      [1, 2, 3],
+      async (item, index, { breakNow }) => {
+        if (item === 2) {
+          breakNow();
+        }
+        return true;
+      },
+    );
+    expect(result).toBe(false);
+  });
+
+  it('stops iterating if the operator function calls the breakNow function', async () => {
+    const mockOperatorFunction = jest.fn(async (item, index, { breakNow }) => {
+      if (item === 2) {
+        breakNow();
+      }
+      return true;
+    });
+    const result = await everyAsync(
+      [1, 2, 3],
+      mockOperatorFunction,
+    );
+    expect(result).toBe(false);
+    expect(mockOperatorFunction).toHaveBeenCalledTimes(2);
+  });
+
+  it('handles an operator function that returns a promise that resolves to true', async () => {
+    const result = await everyAsync(
+      [1, 2, 3],
+      async (item) => {
+        return Promise.resolve(item > 0);
+      },
+    );
+    expect(result).toBe(true);
+  });
+
+  it('handles an operator function that returns a promise that resolves to false', async () => {
+    const result = await everyAsync(
+      [1, 2, 3],
+      async (item) => {
+        return Promise.resolve(item > 1);
+      },
+    );
+    expect(result).toBe(false);
+  });
+
+  it('handles an operator function that throws an error', async () => {
+    const mockOperatorFunction = jest.fn(async (item) => {
+      if (item === 2) {
+        throw new Error('Test error');
+      }
+      return true;
+    });
+    let error: any = null;
+    let result: boolean | null = null;
+    try {
+      result = await everyAsync(
+        [1, 2, 3],
+        mockOperatorFunction,
+      );
+    } catch (err) {
+      error = err;
+    }
+    expect(result).toBe(null);
+    expect(error).not.toBe(null);
+    expect(mockOperatorFunction).toHaveBeenCalledTimes(2);
+  });
+});

package/src/helpers/asyncArrayFunctions/everyAsync.ts

@@ -0,0 +1,51 @@
+/**
+ * Run the operator function on each item in the array, returning true if
+ *   the operator function returns true for every item in the array
+ * @author Gabe Abrams
+ * @param operatorFunction the operator function to apply. If it returns true
+ *   for every item, this function will return true
+ * @returns true if the operator function returns true for every item in the array
+ */
+const everyAsync = async <T>(
+  array: T[],
+  operatorFunction: (
+    item: T,
+    index: number,
+    opts: {
+      breakNow: () => void,
+      array: Array<T>,
+    },
+  ) => Promise<any>,
+): Promise<boolean> => {
+  // Create break logic
+  let done = false;
+  /**
+   * Break the loop (checking stops here)
+   * @author Gabe Abrams
+   */
+  const breakNow = () => {
+    done = true;
+  };
+
+  // Loop through each item, checking
+  for (let i = 0; i < array.length && !done; i++) {
+    const passed = await operatorFunction(
+      array[i],
+      i,
+      {
+        breakNow,
+        array,
+      },
+    );
+
+    // Check if this one failed or if loop was broken
+    if (!passed || done) {
+      return false;
+    }
+  }
+
+  // Return true because none returned false
+  return true;
+};
+
+export default everyAsync;

package/src/helpers/asyncArrayFunctions/filterAsync.test.ts

@@ -0,0 +1,126 @@
+import filterAsync from './filterAsync';
+
+describe('filterAsync', () => {
+  it('should return an empty array when given an empty array', async () => {
+    const result = await filterAsync(
+      [],
+      async () => {
+        return true;
+      },
+    );
+    expect(result).toEqual([]);
+  });
+
+  it('should return the original array when all items pass the filter', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async () => {
+        return true;
+      },
+    );
+    expect(result).toEqual(originalArray);
+  });
+
+  it('should return an empty array when no items pass the filter', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async () => {
+        return false;
+      },
+    );
+    expect(result).toEqual([]);
+  });
+
+  it('should return only the items that pass the filter', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async (item) => {
+        return item > 1;
+      },
+    );
+    expect(result).toEqual([2, 3]);
+  });
+
+  it('should pass the correct index to the operator function', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async (_, index) => {
+        return index === 1;
+      },
+    );
+    expect(result).toEqual([2]);
+  });
+
+  it('should allow breaking out of the loop early', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async (_, index, { breakNow }) => {
+        if (index === 1) {
+          breakNow();
+        }
+        return true;
+      },
+    );
+    expect(result).toEqual([1]);
+  });
+
+  it('should pass the original array to the operator function', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async (_, index, { array }) => {
+        return array.length === 3;
+      },
+    );
+    expect(result).toEqual(originalArray);
+  });
+
+  it('should handle an operator function that returns a non-boolean value', async () => {
+    const originalArray = [1, 2, 3];
+    const result = await filterAsync(
+      originalArray,
+      async () => {
+        return 'hello';
+      },
+    );
+    expect(result).toEqual(originalArray);
+  });
+
+  it('should handle an operator function that throws an error', async () => {
+    const originalArray = [1, 2, 3];
+    let error: any = null;
+    let result: number[] | null = null;
+    try {
+      result = await filterAsync(
+        originalArray,
+        async () => {
+          throw new Error('Something went wrong');
+        },
+      );
+    } catch (err) {
+      error = err;
+    }
+    expect(result).toEqual(null);
+    expect(error).not.toBe(null);
+  });
+
+  it('should handle an array of objects', async () => {
+    const originalArray = [
+      { name: 'Alice', age: 30 },
+      { name: 'Bob', age: 25 },
+      { name: 'Charlie', age: 35 },
+    ];
+    const result = await filterAsync(
+      originalArray,
+      async (item) => {
+        return (item.age > 30);
+      },
+    );
+    expect(result).toEqual([{ name: 'Charlie', age: 35 }]);
+  });
+});

package/src/helpers/asyncArrayFunctions/filterAsync.ts

@@ -0,0 +1,50 @@
+/**
+ * Run the operator function on each item in the array, returning a new array
+ *   that only contains the items that pass the filter
+ * @author Gabe Abrams
+ * @param operatorFunction the operator function to apply. If it returns true
+ *   for an item, the item will be included in the returned array
+ * @returns the filtered array
+ */
+const filterAsync = async <T>(
+  array: T[],
+  operatorFunction: (
+    item: T,
+    index: number,
+    opts: {
+      breakNow: () => void,
+      array: Array<T>,
+    },
+  ) => Promise<any>,
+): Promise<T[]> => {
+  // Create break logic
+  let done = false;
+  /**
+   * Break the loop (filtering stops here)
+   * @author Gabe Abrams
+   */
+  const breakNow = () => {
+    done = true;
+  };
+
+  // Loop through each item, filtering
+  const output: T[] = [];
+  for (let i = 0; i < array.length && !done; i++) {
+    const included = await operatorFunction(
+      array[i],
+      i,
+      {
+        breakNow,
+        array,
+      },
+    );
+    if (included && !done) {
+      output.push(array[i]);
+    }
+  }
+
+  // Return results
+  return output;
+};
+
+export default filterAsync;