@kuroson/cse-groups 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @kuroson/cse-groups
+
+## 0.2.1
+
+### Patch Changes
+
+- 61adb1e: Updated dependency `@typescript-eslint/eslint-plugin` to `8.50.1`.
+  Updated dependency `@typescript-eslint/parser` to `8.50.1`.
+  Updated dependency `typescript-eslint` to `8.50.1`.
+  Updated dependency `next` to `16.1.1`.
+  Updated dependency `eslint-config-next` to `16.1.1`.
+  Updated dependency `@next/third-parties` to `16.1.1`.
+  Updated dependency `ldapts` to `8.0.31`.
+  Updated dependency `@next/eslint-plugin-next` to `16.1.1`.
+  Updated dependency `eslint-plugin-jest` to `29.10.1`.
+  Updated dependency `nodemailer` to `7.0.12`.
+- Updated dependencies [61adb1e]
+  - @kuroson/common-utils@0.2.1
+  - @kuroson/cse-students@0.3.1
+
+## 0.2.0
+
+### Minor Changes
+
+- cdb0acc: Initial release
+
+### Patch Changes
+
+- Updated dependencies [cdb0acc]
+  - @kuroson/common-utils@0.2.0
+  - @kuroson/cse-students@0.3.0
+
+## 0.1.0
+
+### Features
+
+- Initial public release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Alvin Cherk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# @kuroson/cse-groups
+
+Group allocation parser for UNSW CSE courses.
+
+## Installation
+
+```bash
+npm install @kuroson/cse-groups
+# or
+pnpm add @kuroson/cse-groups
+# or
+yarn add @kuroson/cse-groups
+```
+
+## Requirements
+
+- Node.js >= 22
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,110 @@
+'use strict';
+
+var commonUtils = require('@kuroson/common-utils');
+var path = require('path');
+require('winston');
+var fs = require('fs');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var path__default = /*#__PURE__*/_interopDefault(path);
+
+// src/Groups.ts
+var readFileFrom = (path2, encoding = "utf-8") => {
+  if (fs.existsSync(path2)) {
+    return fs.readFileSync(path2, encoding);
+  }
+  throw new Error(`Failed to read file from expected directory: ${path2}`);
+};
+
+// src/Groups.ts
+var Groups = class {
+  groupFiles;
+  groups = /* @__PURE__ */ new Map();
+  logger;
+  basePath;
+  constructor(groupFiles, options) {
+    this.groupFiles = [...groupFiles];
+    this.logger = options?.logger;
+    this.basePath = options.basePath;
+    for (const groupFile of this.groupFiles) {
+      const readPath = path__default.default.join(this.basePath, groupFile.fileName);
+      this.logger?.verbose(`Reading from ${readPath} for '${groupFile.assignment}'`);
+      try {
+        const input = readFileFrom(readPath, "utf-8");
+        const lines = input.split("\n").slice(1).filter((x) => x.length !== 0);
+        const groups = {};
+        for (const line of lines) {
+          const [id, group] = line.split(",");
+          groups[id.startsWith("z") ? id : `z${id}`] = group === "null" || group.length === 0 ? null : group;
+        }
+        this.groups.set(groupFile.assignment, { ...groups });
+        this.logger?.verbose(`Read ${Object.keys(groups).length} groups for '${groupFile.assignment}'`);
+      } catch (err) {
+        this.logger?.error(`Failed to read from ${groupFile.fileName}`);
+        this.logger?.error(commonUtils.parseError(err));
+      }
+    }
+  }
+  /**
+   * Gets a map of zIDs to group names for a given assignment
+   * @param assignment given assignment to get groups for
+   */
+  getGroups = (assignment) => {
+    if (this.groups.has(assignment)) {
+      return { ...this.groups.get(assignment) };
+    }
+    return {};
+  };
+  /**
+   * Gets a map of zIDs to group names, and student names for a given assignment.
+   * If a student is not found, they are not included in the output.
+   * @param assignment given assignment to get groups for
+   * @param allStudents array of all students
+   */
+  getGroupsFullInfo = (assignment, allStudents) => {
+    const groups = this.getGroups(assignment);
+    const output = {};
+    for (const [zID, group] of Object.entries(groups)) {
+      const student = allStudents.find((s) => s.zID === zID);
+      if (student === void 0) {
+        this.logger?.error(`Could not find student with zID: ${zID}`);
+        continue;
+      }
+      output[zID] = { ...student, group };
+    }
+    return output;
+  };
+  /**
+   * Gets all the groups for a given assignment
+   * @param assignment given assignment to get groups for
+   */
+  getAllGroups = (assignment) => {
+    return Array.from(new Set(Object.values(this.groups.get(assignment) ?? {}))).filter((x) => x !== null);
+  };
+  /**
+   * Gets a map of group names to students for a given assignment
+   * @param assignment given assignment to get groups for
+   * @param allStudents array of all students
+   */
+  getByGroupNames = (assignment, allStudents) => {
+    const groups = this.getGroups(assignment);
+    const stuff = {};
+    for (const [zID, group] of Object.entries(groups)) {
+      const student = allStudents.find((s) => s.zID === zID);
+      if (group === null || student === void 0) {
+        continue;
+      }
+      if (stuff[group] === void 0) {
+        stuff[group] = [{ ...student }];
+      } else {
+        stuff[group].push({ ...student });
+      }
+    }
+    return stuff;
+  };
+};
+
+exports.Groups = Groups;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/Groups.ts"],"names":["path","existsSync","readFileSync","parseError"],"mappings":";;;;;;;;;;;;AAQO,IAAM,YAAA,GAAe,CAACA,KAAAA,EAAc,QAAA,GAA2B,OAAA,KAAoB;AACxF,EAAA,IAAIC,aAAA,CAAWD,KAAI,CAAA,EAAG;AACpB,IAAA,OAAOE,eAAA,CAAaF,OAAM,QAAQ,CAAA;AAAA,EACpC;AACA,EAAA,MAAM,IAAI,KAAA,CAAM,CAAA,6CAAA,EAAgDA,KAAI,CAAA,CAAE,CAAA;AACxE,CAAA;;;ACKO,IAAM,SAAN,MAA+B;AAAA,EACnB,UAAA;AAAA,EACA,MAAA,uBAAa,GAAA,EAAwB;AAAA,EACrC,MAAA;AAAA,EACA,QAAA;AAAA,EAEV,WAAA,CAAY,YAAgC,OAAA,EAAwB;AACzE,IAAA,IAAA,CAAK,UAAA,GAAa,CAAC,GAAG,UAAU,CAAA;AAChC,IAAA,IAAA,CAAK,SAAS,OAAA,EAAS,MAAA;AACvB,IAAA,IAAA,CAAK,WAAW,OAAA,CAAQ,QAAA;AAExB,IAAA,KAAA,MAAW,SAAA,IAAa,KAAK,UAAA,EAAY;AACvC,MAAA,MAAM,WAAWA,qBAAA,CAAK,IAAA,CAAK,IAAA,CAAK,QAAA,EAAU,UAAU,QAAQ,CAAA;AAE5D,MAAA,IAAA,CAAK,QAAQ,OAAA,CAAQ,CAAA,aAAA,EAAgB,QAAQ,CAAA,MAAA,EAAS,SAAA,CAAU,UAAU,CAAA,CAAA,CAAG,CAAA;AAC7E,MAAA,IAAI;AACF,QAAA,MAAM,KAAA,GAAQ,YAAA,CAAa,QAAA,EAAU,OAAO,CAAA;AAC5C,QAAA,MAAM,KAAA,GAAQ,KAAA,CACX,KAAA,CAAM,IAAI,CAAA,CACV,KAAA,CAAM,CAAC,CAAA,CACP,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,WAAW,CAAC,CAAA;AAC/B,QAAA,MAAM,SAA0B,EAAC;AACjC,QAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,UAAA,MAAM,CAAC,EAAA,EAAI,KAAK,CAAA,GAAI,IAAA,CAAK,MAAM,GAAG,CAAA;AAClC,UAAA,MAAA,CAAO,EAAA,CAAG,UAAA,CAAW,GAAG,CAAA,GAAI,KAAK,CAAA,CAAA,EAAI,EAAE,CAAA,CAAE,CAAA,GAAI,KAAA,KAAU,MAAA,IAAU,KAAA,CAAM,MAAA,KAAW,IAAI,IAAA,GAAO,KAAA;AAAA,QAC/F;AACA,QAAA,IAAA,CAAK,OAAO,GAAA,CAAI,SAAA,CAAU,YAAY,EAAE,GAAG,QAAQ,CAAA;AACnD,QAAA,IAAA,CAAK,MAAA,EAAQ,OAAA,CAAQ,CAAA,KAAA,EAAQ,MAAA,CAAO,IAAA,CAAK,MAAM,CAAA,CAAE,MAAM,CAAA,aAAA,EAAgB,SAAA,CAAU,UAAU,CAAA,CAAA,CAAG,CAAA;AAAA,MAChG,SAAS,GAAA,EAAc;AACrB,QAAA,IAAA,CAAK,MAAA,EAAQ,KAAA,CAAM,CAAA,oBAAA,EAAuB,SAAA,CAAU,QAAQ,CAAA,CAAE,CAAA;AAC9D,QAAA,IAAA,CAAK,MAAA,EAAQ,KAAA,CAAMG,sBAAA,CAAW,GAAG,CAAC,CAAA;AAAA,MACpC;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,SAAA,GAAY,CAAC,UAAA,KAAmD;AACrE,IAAA,IAAI,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,UAAe,CAAA,EAAG;AACpC,MAAA,OAAO,EAAE,GAAG,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,UAAe,CAAA,EAAE;AAAA,IAC/C;AACA,IAAA,OAAO,EAAC;AAAA,EACV,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQO,iBAAA,GAAoB,CAAC,UAAA,EAAe,WAAA,KAAyD;AAClG,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,SAAA,CAAU,UAAU,CAAA;AACxC,IAAA,MAAM,SAA8B,EAAC;AACrC,IAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAAG;AACjD,MAAA,MAAM,UAAU,WAAA,CAAY,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,QAAQ,GAAG,CAAA;AACrD,MAAA,IAAI,YAAY,MAAA,EAAW;AACzB,QAAA,IAAA,CAAK,MAAA,EAAQ,KAAA,CAAM,CAAA,iCAAA,EAAoC,GAAG,CAAA,CAAE,CAAA;AAC5D,QAAA;AAAA,MACF;AACA,MAAA,MAAA,CAAO,GAAG,CAAA,GAAI,EAAE,GAAG,SAAS,KAAA,EAAa;AAAA,IAC3C;AACA,IAAA,OAAO,MAAA;AAAA,EACT,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,YAAA,GAAe,CAAC,UAAA,KAAkB;AACvC,IAAA,OAAO,KAAA,CAAM,KAAK,IAAI,GAAA,CAAI,OAAO,MAAA,CAAO,IAAA,CAAK,OAAO,GAAA,CAAI,UAAU,KAAK,EAAE,CAAC,CAAC,CAAA,CAAE,OAAO,CAAC,CAAA,KAAM,MAAM,IAAI,CAAA;AAAA,EACvG,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,eAAA,GAAkB,CAAC,UAAA,EAAe,WAAA,KAAuD;AAC9F,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,SAAA,CAAU,UAAU,CAAA;AACxC,IAAA,MAAM,QAA2B,EAAC;AAClC,IAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAAG;AACjD,MAAA,MAAM,UAAU,WAAA,CAAY,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,QAAQ,GAAG,CAAA;AAErD,MAAA,IAAI,KAAA,KAAU,IAAA,IAAQ,OAAA,KAAY,MAAA,EAAW;AAC3C,QAAA;AAAA,MACF;AACA,MAAA,IAAI,KAAA,CAAM,KAAK,CAAA,KAAM,MAAA,EAAW;AAC9B,QAAA,KAAA,CAAM,KAAK,CAAA,GAAI,CAAC,EAAE,GAAG,SAAS,CAAA;AAAA,MAChC,CAAA,MAAO;AACL,QAAA,KAAA,CAAM,KAAK,CAAA,CAAE,IAAA,CAAK,EAAE,GAAG,SAAS,CAAA;AAAA,MAClC;AAAA,IACF;AACA,IAAA,OAAO,KAAA;AAAA,EACT,CAAA;AACF","file":"index.cjs","sourcesContent":["import { existsSync, readFileSync } from 'fs';\n\n/**\n * Reads input from a file and returns a string\n * @throws { Error } if the file does not exist\n * @param path path of file\n * @param encoding encoding, defaulted to \"utf-8\"\n */\nexport const readFileFrom = (path: string, encoding: BufferEncoding = 'utf-8'): string => {\n  if (existsSync(path)) {\n    return readFileSync(path, encoding);\n  }\n  throw new Error(`Failed to read file from expected directory: ${path}`);\n};\n","import { parseError } from '@kuroson/common-utils';\nimport type { StudentEnrolment } from '@kuroson/cse-students';\nimport path from 'path';\nimport { type Logger } from 'winston';\nimport type { GroupByStudentMap, GroupFileInfo, StudentGroupMap, StudentGroupMapFull } from './types';\nimport { readFileFrom } from './utils';\n\ntype GroupsOptions = {\n  /**\n   * Optional logger for verbose and error logging\n   */\n  logger?: Logger;\n  /**\n   * Base path for reading group files.\n   */\n  basePath: string;\n};\n\nexport class Groups<T extends string> {\n  private readonly groupFiles: GroupFileInfo<T>[];\n  private readonly groups = new Map<T, StudentGroupMap>();\n  private readonly logger: Logger | undefined;\n  private readonly basePath: string;\n\n  public constructor(groupFiles: GroupFileInfo<T>[], options: GroupsOptions) {\n    this.groupFiles = [...groupFiles];\n    this.logger = options?.logger;\n    this.basePath = options.basePath;\n\n    for (const groupFile of this.groupFiles) {\n      const readPath = path.join(this.basePath, groupFile.fileName);\n\n      this.logger?.verbose(`Reading from ${readPath} for '${groupFile.assignment}'`);\n      try {\n        const input = readFileFrom(readPath, 'utf-8');\n        const lines = input\n          .split('\\n')\n          .slice(1)\n          .filter((x) => x.length !== 0);\n        const groups: StudentGroupMap = {};\n        for (const line of lines) {\n          const [id, group] = line.split(',') as [string, string];\n          groups[id.startsWith('z') ? id : `z${id}`] = group === 'null' || group.length === 0 ? null : group;\n        }\n        this.groups.set(groupFile.assignment, { ...groups });\n        this.logger?.verbose(`Read ${Object.keys(groups).length} groups for '${groupFile.assignment}'`);\n      } catch (err: unknown) {\n        this.logger?.error(`Failed to read from ${groupFile.fileName}`);\n        this.logger?.error(parseError(err));\n      }\n    }\n  }\n\n  /**\n   * Gets a map of zIDs to group names for a given assignment\n   * @param assignment given assignment to get groups for\n   */\n  public getGroups = (assignment: T | (string & {})): StudentGroupMap => {\n    if (this.groups.has(assignment as T)) {\n      return { ...this.groups.get(assignment as T) };\n    }\n    return {};\n  };\n\n  /**\n   * Gets a map of zIDs to group names, and student names for a given assignment.\n   * If a student is not found, they are not included in the output.\n   * @param assignment given assignment to get groups for\n   * @param allStudents array of all students\n   */\n  public getGroupsFullInfo = (assignment: T, allStudents: StudentEnrolment[]): StudentGroupMapFull => {\n    const groups = this.getGroups(assignment);\n    const output: StudentGroupMapFull = {};\n    for (const [zID, group] of Object.entries(groups)) {\n      const student = allStudents.find((s) => s.zID === zID);\n      if (student === undefined) {\n        this.logger?.error(`Could not find student with zID: ${zID}`);\n        continue;\n      }\n      output[zID] = { ...student, group: group };\n    }\n    return output;\n  };\n\n  /**\n   * Gets all the groups for a given assignment\n   * @param assignment given assignment to get groups for\n   */\n  public getAllGroups = (assignment: T) => {\n    return Array.from(new Set(Object.values(this.groups.get(assignment) ?? {}))).filter((x) => x !== null);\n  };\n\n  /**\n   * Gets a map of group names to students for a given assignment\n   * @param assignment given assignment to get groups for\n   * @param allStudents array of all students\n   */\n  public getByGroupNames = (assignment: T, allStudents: StudentEnrolment[]): GroupByStudentMap => {\n    const groups = this.getGroups(assignment);\n    const stuff: GroupByStudentMap = {};\n    for (const [zID, group] of Object.entries(groups)) {\n      const student = allStudents.find((s) => s.zID === zID);\n\n      if (group === null || student === undefined) {\n        continue;\n      }\n      if (stuff[group] === undefined) {\n        stuff[group] = [{ ...student }];\n      } else {\n        stuff[group].push({ ...student });\n      }\n    }\n    return stuff;\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,73 @@
+import { StudentEnrolment } from '@kuroson/cse-students';
+import { Logger } from 'winston';
+
+/**
+ * Information about a group file
+ */
+type GroupFileInfo<T extends string> = {
+    /**
+     * Path relative to the base path (or absolute path)
+     */
+    fileName: string;
+    /**
+     * Assignment identifier
+     */
+    assignment: T;
+};
+type StudentGroupMap = {
+    [zID: string]: string | null;
+};
+type GroupByStudentMap = {
+    [group: string]: StudentEnrolment[];
+};
+type StudentGroupMapFull = {
+    [zID: string]: StudentEnrolment & {
+        /**
+         * Name of their Group for a specific assignment
+         */
+        group: string | null;
+    };
+};
+
+type GroupsOptions = {
+    /**
+     * Optional logger for verbose and error logging
+     */
+    logger?: Logger;
+    /**
+     * Base path for reading group files.
+     */
+    basePath: string;
+};
+declare class Groups<T extends string> {
+    private readonly groupFiles;
+    private readonly groups;
+    private readonly logger;
+    private readonly basePath;
+    constructor(groupFiles: GroupFileInfo<T>[], options: GroupsOptions);
+    /**
+     * Gets a map of zIDs to group names for a given assignment
+     * @param assignment given assignment to get groups for
+     */
+    getGroups: (assignment: T | (string & {})) => StudentGroupMap;
+    /**
+     * Gets a map of zIDs to group names, and student names for a given assignment.
+     * If a student is not found, they are not included in the output.
+     * @param assignment given assignment to get groups for
+     * @param allStudents array of all students
+     */
+    getGroupsFullInfo: (assignment: T, allStudents: StudentEnrolment[]) => StudentGroupMapFull;
+    /**
+     * Gets all the groups for a given assignment
+     * @param assignment given assignment to get groups for
+     */
+    getAllGroups: (assignment: T) => string[];
+    /**
+     * Gets a map of group names to students for a given assignment
+     * @param assignment given assignment to get groups for
+     * @param allStudents array of all students
+     */
+    getByGroupNames: (assignment: T, allStudents: StudentEnrolment[]) => GroupByStudentMap;
+}
+
+export { type GroupByStudentMap, type GroupFileInfo, Groups, type StudentGroupMap, type StudentGroupMapFull };

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import { StudentEnrolment } from '@kuroson/cse-students';
+import { Logger } from 'winston';
+
+/**
+ * Information about a group file
+ */
+type GroupFileInfo<T extends string> = {
+    /**
+     * Path relative to the base path (or absolute path)
+     */
+    fileName: string;
+    /**
+     * Assignment identifier
+     */
+    assignment: T;
+};
+type StudentGroupMap = {
+    [zID: string]: string | null;
+};
+type GroupByStudentMap = {
+    [group: string]: StudentEnrolment[];
+};
+type StudentGroupMapFull = {
+    [zID: string]: StudentEnrolment & {
+        /**
+         * Name of their Group for a specific assignment
+         */
+        group: string | null;
+    };
+};
+
+type GroupsOptions = {
+    /**
+     * Optional logger for verbose and error logging
+     */
+    logger?: Logger;
+    /**
+     * Base path for reading group files.
+     */
+    basePath: string;
+};
+declare class Groups<T extends string> {
+    private readonly groupFiles;
+    private readonly groups;
+    private readonly logger;
+    private readonly basePath;
+    constructor(groupFiles: GroupFileInfo<T>[], options: GroupsOptions);
+    /**
+     * Gets a map of zIDs to group names for a given assignment
+     * @param assignment given assignment to get groups for
+     */
+    getGroups: (assignment: T | (string & {})) => StudentGroupMap;
+    /**
+     * Gets a map of zIDs to group names, and student names for a given assignment.
+     * If a student is not found, they are not included in the output.
+     * @param assignment given assignment to get groups for
+     * @param allStudents array of all students
+     */
+    getGroupsFullInfo: (assignment: T, allStudents: StudentEnrolment[]) => StudentGroupMapFull;
+    /**
+     * Gets all the groups for a given assignment
+     * @param assignment given assignment to get groups for
+     */
+    getAllGroups: (assignment: T) => string[];
+    /**
+     * Gets a map of group names to students for a given assignment
+     * @param assignment given assignment to get groups for
+     * @param allStudents array of all students
+     */
+    getByGroupNames: (assignment: T, allStudents: StudentEnrolment[]) => GroupByStudentMap;
+}
+
+export { type GroupByStudentMap, type GroupFileInfo, Groups, type StudentGroupMap, type StudentGroupMapFull };

package/dist/index.js

@@ -0,0 +1,104 @@
+import { parseError } from '@kuroson/common-utils';
+import path from 'path';
+import 'winston';
+import { existsSync, readFileSync } from 'fs';
+
+// src/Groups.ts
+var readFileFrom = (path2, encoding = "utf-8") => {
+  if (existsSync(path2)) {
+    return readFileSync(path2, encoding);
+  }
+  throw new Error(`Failed to read file from expected directory: ${path2}`);
+};
+
+// src/Groups.ts
+var Groups = class {
+  groupFiles;
+  groups = /* @__PURE__ */ new Map();
+  logger;
+  basePath;
+  constructor(groupFiles, options) {
+    this.groupFiles = [...groupFiles];
+    this.logger = options?.logger;
+    this.basePath = options.basePath;
+    for (const groupFile of this.groupFiles) {
+      const readPath = path.join(this.basePath, groupFile.fileName);
+      this.logger?.verbose(`Reading from ${readPath} for '${groupFile.assignment}'`);
+      try {
+        const input = readFileFrom(readPath, "utf-8");
+        const lines = input.split("\n").slice(1).filter((x) => x.length !== 0);
+        const groups = {};
+        for (const line of lines) {
+          const [id, group] = line.split(",");
+          groups[id.startsWith("z") ? id : `z${id}`] = group === "null" || group.length === 0 ? null : group;
+        }
+        this.groups.set(groupFile.assignment, { ...groups });
+        this.logger?.verbose(`Read ${Object.keys(groups).length} groups for '${groupFile.assignment}'`);
+      } catch (err) {
+        this.logger?.error(`Failed to read from ${groupFile.fileName}`);
+        this.logger?.error(parseError(err));
+      }
+    }
+  }
+  /**
+   * Gets a map of zIDs to group names for a given assignment
+   * @param assignment given assignment to get groups for
+   */
+  getGroups = (assignment) => {
+    if (this.groups.has(assignment)) {
+      return { ...this.groups.get(assignment) };
+    }
+    return {};
+  };
+  /**
+   * Gets a map of zIDs to group names, and student names for a given assignment.
+   * If a student is not found, they are not included in the output.
+   * @param assignment given assignment to get groups for
+   * @param allStudents array of all students
+   */
+  getGroupsFullInfo = (assignment, allStudents) => {
+    const groups = this.getGroups(assignment);
+    const output = {};
+    for (const [zID, group] of Object.entries(groups)) {
+      const student = allStudents.find((s) => s.zID === zID);
+      if (student === void 0) {
+        this.logger?.error(`Could not find student with zID: ${zID}`);
+        continue;
+      }
+      output[zID] = { ...student, group };
+    }
+    return output;
+  };
+  /**
+   * Gets all the groups for a given assignment
+   * @param assignment given assignment to get groups for
+   */
+  getAllGroups = (assignment) => {
+    return Array.from(new Set(Object.values(this.groups.get(assignment) ?? {}))).filter((x) => x !== null);
+  };
+  /**
+   * Gets a map of group names to students for a given assignment
+   * @param assignment given assignment to get groups for
+   * @param allStudents array of all students
+   */
+  getByGroupNames = (assignment, allStudents) => {
+    const groups = this.getGroups(assignment);
+    const stuff = {};
+    for (const [zID, group] of Object.entries(groups)) {
+      const student = allStudents.find((s) => s.zID === zID);
+      if (group === null || student === void 0) {
+        continue;
+      }
+      if (stuff[group] === void 0) {
+        stuff[group] = [{ ...student }];
+      } else {
+        stuff[group].push({ ...student });
+      }
+    }
+    return stuff;
+  };
+};
+
+export { Groups };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/utils.ts","../src/Groups.ts"],"names":["path"],"mappings":";;;;;;AAQO,IAAM,YAAA,GAAe,CAACA,KAAAA,EAAc,QAAA,GAA2B,OAAA,KAAoB;AACxF,EAAA,IAAI,UAAA,CAAWA,KAAI,CAAA,EAAG;AACpB,IAAA,OAAO,YAAA,CAAaA,OAAM,QAAQ,CAAA;AAAA,EACpC;AACA,EAAA,MAAM,IAAI,KAAA,CAAM,CAAA,6CAAA,EAAgDA,KAAI,CAAA,CAAE,CAAA;AACxE,CAAA;;;ACKO,IAAM,SAAN,MAA+B;AAAA,EACnB,UAAA;AAAA,EACA,MAAA,uBAAa,GAAA,EAAwB;AAAA,EACrC,MAAA;AAAA,EACA,QAAA;AAAA,EAEV,WAAA,CAAY,YAAgC,OAAA,EAAwB;AACzE,IAAA,IAAA,CAAK,UAAA,GAAa,CAAC,GAAG,UAAU,CAAA;AAChC,IAAA,IAAA,CAAK,SAAS,OAAA,EAAS,MAAA;AACvB,IAAA,IAAA,CAAK,WAAW,OAAA,CAAQ,QAAA;AAExB,IAAA,KAAA,MAAW,SAAA,IAAa,KAAK,UAAA,EAAY;AACvC,MAAA,MAAM,WAAW,IAAA,CAAK,IAAA,CAAK,IAAA,CAAK,QAAA,EAAU,UAAU,QAAQ,CAAA;AAE5D,MAAA,IAAA,CAAK,QAAQ,OAAA,CAAQ,CAAA,aAAA,EAAgB,QAAQ,CAAA,MAAA,EAAS,SAAA,CAAU,UAAU,CAAA,CAAA,CAAG,CAAA;AAC7E,MAAA,IAAI;AACF,QAAA,MAAM,KAAA,GAAQ,YAAA,CAAa,QAAA,EAAU,OAAO,CAAA;AAC5C,QAAA,MAAM,KAAA,GAAQ,KAAA,CACX,KAAA,CAAM,IAAI,CAAA,CACV,KAAA,CAAM,CAAC,CAAA,CACP,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,WAAW,CAAC,CAAA;AAC/B,QAAA,MAAM,SAA0B,EAAC;AACjC,QAAA,KAAA,MAAW,QAAQ,KAAA,EAAO;AACxB,UAAA,MAAM,CAAC,EAAA,EAAI,KAAK,CAAA,GAAI,IAAA,CAAK,MAAM,GAAG,CAAA;AAClC,UAAA,MAAA,CAAO,EAAA,CAAG,UAAA,CAAW,GAAG,CAAA,GAAI,KAAK,CAAA,CAAA,EAAI,EAAE,CAAA,CAAE,CAAA,GAAI,KAAA,KAAU,MAAA,IAAU,KAAA,CAAM,MAAA,KAAW,IAAI,IAAA,GAAO,KAAA;AAAA,QAC/F;AACA,QAAA,IAAA,CAAK,OAAO,GAAA,CAAI,SAAA,CAAU,YAAY,EAAE,GAAG,QAAQ,CAAA;AACnD,QAAA,IAAA,CAAK,MAAA,EAAQ,OAAA,CAAQ,CAAA,KAAA,EAAQ,MAAA,CAAO,IAAA,CAAK,MAAM,CAAA,CAAE,MAAM,CAAA,aAAA,EAAgB,SAAA,CAAU,UAAU,CAAA,CAAA,CAAG,CAAA;AAAA,MAChG,SAAS,GAAA,EAAc;AACrB,QAAA,IAAA,CAAK,MAAA,EAAQ,KAAA,CAAM,CAAA,oBAAA,EAAuB,SAAA,CAAU,QAAQ,CAAA,CAAE,CAAA;AAC9D,QAAA,IAAA,CAAK,MAAA,EAAQ,KAAA,CAAM,UAAA,CAAW,GAAG,CAAC,CAAA;AAAA,MACpC;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,SAAA,GAAY,CAAC,UAAA,KAAmD;AACrE,IAAA,IAAI,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,UAAe,CAAA,EAAG;AACpC,MAAA,OAAO,EAAE,GAAG,IAAA,CAAK,MAAA,CAAO,GAAA,CAAI,UAAe,CAAA,EAAE;AAAA,IAC/C;AACA,IAAA,OAAO,EAAC;AAAA,EACV,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQO,iBAAA,GAAoB,CAAC,UAAA,EAAe,WAAA,KAAyD;AAClG,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,SAAA,CAAU,UAAU,CAAA;AACxC,IAAA,MAAM,SAA8B,EAAC;AACrC,IAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAAG;AACjD,MAAA,MAAM,UAAU,WAAA,CAAY,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,QAAQ,GAAG,CAAA;AACrD,MAAA,IAAI,YAAY,MAAA,EAAW;AACzB,QAAA,IAAA,CAAK,MAAA,EAAQ,KAAA,CAAM,CAAA,iCAAA,EAAoC,GAAG,CAAA,CAAE,CAAA;AAC5D,QAAA;AAAA,MACF;AACA,MAAA,MAAA,CAAO,GAAG,CAAA,GAAI,EAAE,GAAG,SAAS,KAAA,EAAa;AAAA,IAC3C;AACA,IAAA,OAAO,MAAA;AAAA,EACT,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMO,YAAA,GAAe,CAAC,UAAA,KAAkB;AACvC,IAAA,OAAO,KAAA,CAAM,KAAK,IAAI,GAAA,CAAI,OAAO,MAAA,CAAO,IAAA,CAAK,OAAO,GAAA,CAAI,UAAU,KAAK,EAAE,CAAC,CAAC,CAAA,CAAE,OAAO,CAAC,CAAA,KAAM,MAAM,IAAI,CAAA;AAAA,EACvG,CAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,eAAA,GAAkB,CAAC,UAAA,EAAe,WAAA,KAAuD;AAC9F,IAAA,MAAM,MAAA,GAAS,IAAA,CAAK,SAAA,CAAU,UAAU,CAAA;AACxC,IAAA,MAAM,QAA2B,EAAC;AAClC,IAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,MAAM,CAAA,EAAG;AACjD,MAAA,MAAM,UAAU,WAAA,CAAY,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,QAAQ,GAAG,CAAA;AAErD,MAAA,IAAI,KAAA,KAAU,IAAA,IAAQ,OAAA,KAAY,MAAA,EAAW;AAC3C,QAAA;AAAA,MACF;AACA,MAAA,IAAI,KAAA,CAAM,KAAK,CAAA,KAAM,MAAA,EAAW;AAC9B,QAAA,KAAA,CAAM,KAAK,CAAA,GAAI,CAAC,EAAE,GAAG,SAAS,CAAA;AAAA,MAChC,CAAA,MAAO;AACL,QAAA,KAAA,CAAM,KAAK,CAAA,CAAE,IAAA,CAAK,EAAE,GAAG,SAAS,CAAA;AAAA,MAClC;AAAA,IACF;AACA,IAAA,OAAO,KAAA;AAAA,EACT,CAAA;AACF","file":"index.js","sourcesContent":["import { existsSync, readFileSync } from 'fs';\n\n/**\n * Reads input from a file and returns a string\n * @throws { Error } if the file does not exist\n * @param path path of file\n * @param encoding encoding, defaulted to \"utf-8\"\n */\nexport const readFileFrom = (path: string, encoding: BufferEncoding = 'utf-8'): string => {\n  if (existsSync(path)) {\n    return readFileSync(path, encoding);\n  }\n  throw new Error(`Failed to read file from expected directory: ${path}`);\n};\n","import { parseError } from '@kuroson/common-utils';\nimport type { StudentEnrolment } from '@kuroson/cse-students';\nimport path from 'path';\nimport { type Logger } from 'winston';\nimport type { GroupByStudentMap, GroupFileInfo, StudentGroupMap, StudentGroupMapFull } from './types';\nimport { readFileFrom } from './utils';\n\ntype GroupsOptions = {\n  /**\n   * Optional logger for verbose and error logging\n   */\n  logger?: Logger;\n  /**\n   * Base path for reading group files.\n   */\n  basePath: string;\n};\n\nexport class Groups<T extends string> {\n  private readonly groupFiles: GroupFileInfo<T>[];\n  private readonly groups = new Map<T, StudentGroupMap>();\n  private readonly logger: Logger | undefined;\n  private readonly basePath: string;\n\n  public constructor(groupFiles: GroupFileInfo<T>[], options: GroupsOptions) {\n    this.groupFiles = [...groupFiles];\n    this.logger = options?.logger;\n    this.basePath = options.basePath;\n\n    for (const groupFile of this.groupFiles) {\n      const readPath = path.join(this.basePath, groupFile.fileName);\n\n      this.logger?.verbose(`Reading from ${readPath} for '${groupFile.assignment}'`);\n      try {\n        const input = readFileFrom(readPath, 'utf-8');\n        const lines = input\n          .split('\\n')\n          .slice(1)\n          .filter((x) => x.length !== 0);\n        const groups: StudentGroupMap = {};\n        for (const line of lines) {\n          const [id, group] = line.split(',') as [string, string];\n          groups[id.startsWith('z') ? id : `z${id}`] = group === 'null' || group.length === 0 ? null : group;\n        }\n        this.groups.set(groupFile.assignment, { ...groups });\n        this.logger?.verbose(`Read ${Object.keys(groups).length} groups for '${groupFile.assignment}'`);\n      } catch (err: unknown) {\n        this.logger?.error(`Failed to read from ${groupFile.fileName}`);\n        this.logger?.error(parseError(err));\n      }\n    }\n  }\n\n  /**\n   * Gets a map of zIDs to group names for a given assignment\n   * @param assignment given assignment to get groups for\n   */\n  public getGroups = (assignment: T | (string & {})): StudentGroupMap => {\n    if (this.groups.has(assignment as T)) {\n      return { ...this.groups.get(assignment as T) };\n    }\n    return {};\n  };\n\n  /**\n   * Gets a map of zIDs to group names, and student names for a given assignment.\n   * If a student is not found, they are not included in the output.\n   * @param assignment given assignment to get groups for\n   * @param allStudents array of all students\n   */\n  public getGroupsFullInfo = (assignment: T, allStudents: StudentEnrolment[]): StudentGroupMapFull => {\n    const groups = this.getGroups(assignment);\n    const output: StudentGroupMapFull = {};\n    for (const [zID, group] of Object.entries(groups)) {\n      const student = allStudents.find((s) => s.zID === zID);\n      if (student === undefined) {\n        this.logger?.error(`Could not find student with zID: ${zID}`);\n        continue;\n      }\n      output[zID] = { ...student, group: group };\n    }\n    return output;\n  };\n\n  /**\n   * Gets all the groups for a given assignment\n   * @param assignment given assignment to get groups for\n   */\n  public getAllGroups = (assignment: T) => {\n    return Array.from(new Set(Object.values(this.groups.get(assignment) ?? {}))).filter((x) => x !== null);\n  };\n\n  /**\n   * Gets a map of group names to students for a given assignment\n   * @param assignment given assignment to get groups for\n   * @param allStudents array of all students\n   */\n  public getByGroupNames = (assignment: T, allStudents: StudentEnrolment[]): GroupByStudentMap => {\n    const groups = this.getGroups(assignment);\n    const stuff: GroupByStudentMap = {};\n    for (const [zID, group] of Object.entries(groups)) {\n      const student = allStudents.find((s) => s.zID === zID);\n\n      if (group === null || student === undefined) {\n        continue;\n      }\n      if (stuff[group] === undefined) {\n        stuff[group] = [{ ...student }];\n      } else {\n        stuff[group].push({ ...student });\n      }\n    }\n    return stuff;\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@kuroson/cse-groups",
+  "version": "0.2.1",
+  "description": "Group allocation parser for UNSW CSE courses",
+  "license": "MIT",
+  "author": "Alvin Cherk <a.cherk@unsw.edu.au>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@kuroson/common-utils": "0.2.1",
+    "@kuroson/cse-students": "0.3.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.2",
+    "@types/jest": "30.0.0",
+    "@types/node": "24.10.4",
+    "@typescript-eslint/eslint-plugin": "8.50.1",
+    "depcheck": "1.4.7",
+    "eslint": "9.39.2",
+    "eslint-config-prettier": "10.1.8",
+    "eslint-plugin-jest": "29.10.1",
+    "eslint-plugin-prettier": "5.5.4",
+    "eslint-plugin-unused-imports": "4.3.0",
+    "jest": "30.2.0",
+    "prettier": "3.7.4",
+    "ts-jest": "29.4.6",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.50.1",
+    "winston": "3.19.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0",
+    "winston": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    },
+    "winston": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "depcheck": {
+    "ignores": [
+      "ts-jest"
+    ],
+    "skip-missing": true
+  },
+  "scripts": {
+    "build:all": "tsup",
+    "depcheck": "depcheck",
+    "lint": "eslint './**/*.{ts,js}'",
+    "lint:fix": "eslint './**/*.{ts,js}' --fix",
+    "test": "jest",
+    "test:cov": "jest --coverage",
+    "typecheck": "tsc --noEmit"
+  }
+}