@bccampus/utils 0.1.0

package/dist/string/strip-html-tags.d.ts

@@ -0,0 +1 @@
+export declare function stripHtmlTags(text: string): string;

package/dist/string/strip-html-tags.js

@@ -0,0 +1,7 @@
+const htmlTagRegExp = /(<([^>]+)>)/g;
+function stripHtmlTags(text) {
+  return text.replace(htmlTagRegExp, "");
+}
+export {
+  stripHtmlTags
+};

package/dist/string/to-int.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Converts a string (or a number) into a number.
+ * If the input can not be successfully converted, it will return the fallback.
+ * It will not return NaN.
+ * @param value - The value to convert
+ * @param fallback - The value to fallback to. Defaults to 0
+ * @returns number
+ */
+export declare function stringToInt(value: string | number, fallback?: number): number;

package/dist/string/to-int.js

@@ -0,0 +1,10 @@
+function stringToInt(value, fallback = 0) {
+  let returnValue = value;
+  if (typeof returnValue === "string")
+    returnValue = Number.parseInt(returnValue);
+  if (Number.isNaN(returnValue)) returnValue = fallback;
+  return returnValue;
+}
+export {
+  stringToInt
+};

package/dist/string/to-sentence-case.d.ts

@@ -0,0 +1 @@
+export declare const toSentenceCase: <T extends string>(s: T) => string;

package/dist/string/to-sentence-case.js

@@ -0,0 +1,8 @@
+const specialCharRegExp = /[\s-_.+]+/g;
+const toSentenceCase = (s) => (s[0].toUpperCase() + s.slice(1).toLowerCase()).replace(
+  specialCharRegExp,
+  " "
+);
+export {
+  toSentenceCase
+};

package/dist/string/trim.d.ts

@@ -0,0 +1 @@
+export declare function trim(text: string, chars?: string | string[]): string;

package/dist/string/trim.js

@@ -0,0 +1,11 @@
+function trim(text, chars = " ") {
+  let start = 0;
+  let end = text.length;
+  if (!Array.isArray(chars)) chars = [chars];
+  while (start < end && chars.includes(text[start])) start += 1;
+  while (end > start && chars.includes(text[end - 1])) end -= 1;
+  return start > 0 || end < text.length ? text.substring(start, end) : text;
+}
+export {
+  trim
+};

package/dist/string/truncate.d.ts

@@ -0,0 +1 @@
+export declare function truncate(text: string, maxlength?: number, ending?: string): string;

package/dist/string/truncate.js

@@ -0,0 +1,9 @@
+function truncate(text, maxlength = 100, ending = "...") {
+  if (text.length > maxlength) {
+    return text.substring(0, maxlength - ending.length) + ending;
+  }
+  return text;
+}
+export {
+  truncate
+};

package/eslint.config.js

@@ -0,0 +1,19 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import tseslint from 'typescript-eslint'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{ts,tsx}'],
+    extends: [
+      js.configs.recommended,
+      tseslint.configs.recommended,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+    },
+  }
+])

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@bccampus/utils",
+  "version": "0.1.0",
+  "description": "BCcampus' utility box",
+  "type": "module",
+  "license": "UNLICENSED",
+  "exports": {
+    "./array": {
+      "types": "./dist/array/index.d.ts",
+      "import": "./dist/array/index.js"
+    },
+    "./date": {
+      "types": "./dist/date/index.d.ts",
+      "import": "./dist/date/index.js"
+    },
+    "./duration": {
+      "types": "./dist/duration/index.d.ts",
+      "import": "./dist/duration/index.js"
+    },
+    "./format": {
+      "types": "./dist/format/index.d.ts",
+      "import": "./dist/format/index.js"
+    },
+    "./object": {
+      "types": "./dist/object/index.d.ts",
+      "import": "./dist/object/index.js"
+    },
+    "./set": {
+      "types": "./dist/set/index.d.ts",
+      "import": "./dist/set/index.js"
+    },
+    "./string": {
+      "types": "./dist/string/index.d.ts",
+      "import": "./dist/string/index.js"
+    },
+    "./string/pluralize": {
+      "types": "./dist/string/pluralize/index.d.ts",
+      "import": "./dist/string/pluralize/index.js"
+    },
+    "./string/slugify": {
+      "types": "./dist/string/slugify/index.d.ts",
+      "import": "./dist/string/slugify/index.js"
+    }
+  },
+  "packageManager": "yarn@4.15.0",
+  "scripts": {
+    "check": "tsc -b && eslint ./src",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "prepublish": "yarn build",
+    "publish": "yarn npm publish --access public --tolerate-republish"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@types/node": "^24.12.3",
+    "baseline-browser-mapping": "^2.10.27",
+    "eslint": "^9.39.4",
+    "globals": "^17.6.0",
+    "tinyglobby": "^0.2.16",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.59.2",
+    "vite": "^7.3.3",
+    "vite-plugin-dts": "^4.5.4"
+  },
+  "dependencies": {
+    "@sindresorhus/slugify": "^3.0.0"
+  }
+}

package/src/array/chunk.ts

@@ -0,0 +1,6 @@
+export function chunk<T>(arr: T[], size: number = 5) {
+  const chunks: T[][] = [];
+  for (let i = 0; i < arr.length; i += size)
+    chunks.push(arr.slice(i, i + size));
+  return chunks;
+}

package/src/array/index.ts

@@ -0,0 +1 @@
+export * from "./chunk";

package/src/date/index.ts

@@ -0,0 +1 @@
+export * from "./iso-date-time";

package/src/date/iso-date-time.ts

@@ -0,0 +1,356 @@
+const isoDateTimeRegEx = new RegExp('^([0-9-]+)(T([0-9:.,]+)(Z|[+-]([0-9:]+))?)?$');
+const dateRegEx = new RegExp('^(\\d{4})-?(\\d{2})?-?(\\d{2})?$');
+const timeRegEx = new RegExp('^(\\d{2}):?(\\d{2})?:?(\\d{2})?(\\.(\\d{3}))?$');
+const timezoneRegEx = new RegExp('^Z|^[+-]((\\d{2}):?(\\d{2})?)$');
+
+export const InvalidDate: unique symbol = Symbol('Invalid Date');
+export type InvalidDate = typeof InvalidDate;
+
+export const DefaultDateFormat: DateFormatOptions = {
+  year: 'numeric',
+  month: 'long',
+  day: '2-digit',
+};
+
+export const DefaultTimeFormat: DateFormatOptions = {
+  hour: '2-digit',
+  minute: '2-digit',
+  timeZoneName: 'short',
+};
+
+export const DefaultTimezone = 'America/Vancouver';
+
+/**
+ * Enables storage, retrieval and formating of ISO dates and times
+ * with time zone information.
+ */
+export class ISODateTime {
+  #parsed?: ParsedDateTime;
+  #date: Date | InvalidDate;
+  #string: string;
+
+  constructor();
+  constructor(isoDatetime: number);
+  constructor(isoDatetime: string);
+  constructor(isoDatetime?: string | number) {
+    if (typeof isoDatetime === 'string') {
+      this.#parsed = ISODateTime.parse(isoDatetime);
+      if (this.#parsed) {
+        this.#date = new Date(ISODateTime.toString(this));
+      } else {
+        this.#date = InvalidDate;
+        console.error(`Failed to parse date for value: ${isoDatetime}`);
+      }
+    } else if (typeof isoDatetime === 'number' && Number.isFinite(isoDatetime)) {
+      this.#date = new Date(isoDatetime);
+      this.#parsed = ISODateTime.parse(this.#date.toISOString());
+    } else {
+      this.#date = new Date();
+      this.#parsed = ISODateTime.parse(this.#date.toISOString());
+    }
+
+    if (this.#date !== InvalidDate) this.#string = this.#date.toISOString();
+    else this.#string = 'Invalid Date';
+  }
+
+  /**
+   * Get date and time components
+   */
+  get parts() {
+    return this.#parsed;
+  }
+
+  /**
+   * Get timezone
+   */
+  get timezone() {
+    return this.parts?.timezone ?? 'UTC';
+  }
+
+  /**
+   * Parse a string in ISO DateTime format.
+   * If the input is valid, returns date and time components;
+   * otherwise, returns `undefined`.
+   */
+  static parse(isoDatetime: string) {
+    const isoDatetimeParts = isoDatetime.match(isoDateTimeRegEx);
+    if (isoDatetimeParts) {
+      const dateParts = isoDatetimeParts[1] && isoDatetimeParts[1].match(dateRegEx);
+      if (!dateParts) return undefined;
+      const parsedDateTime: ParsedDateTime = {
+        date: { year: dateParts[1], month: dateParts[2], day: dateParts[3] },
+      };
+
+      const timeParts = isoDatetimeParts[3] && isoDatetimeParts[3].match(timeRegEx);
+      if (timeParts) {
+        parsedDateTime.time = {
+          hours: timeParts[1],
+          minutes: timeParts[2],
+          seconds: timeParts[3],
+          milliseconds: timeParts[5],
+        };
+      }
+
+      const tzParts = isoDatetimeParts[4] && isoDatetimeParts[4].match(timezoneRegEx);
+      if (tzParts) {
+        parsedDateTime.timezone = tzParts[0] as ISOTimezone;
+      }
+
+      return parsedDateTime;
+    }
+
+    return undefined;
+  }
+
+  static getISOString(parts?: ParsedDateTime) {
+    if (!parts) return 'Invalid Date';
+    return `${parts.date.year}-${parts.date.month ?? '01'}-${parts.date.day ?? '01'}T${parts.time?.hours ?? '00'}:${parts.time?.minutes ?? '00'}:${parts.time?.seconds ?? '00'}.${parts.time?.milliseconds ?? '000'}${parts.timezone ?? 'Z'}`;
+  }
+
+  /**
+   * Retruns ISO date and time string
+   */
+  static toString(parsedDateTime: string): string;
+  static toString(parsedDateTime: ISODateTime): string;
+  static toString(dateTime: ISODateTime | string) {
+    const _p = typeof dateTime === 'string' ? ISODateTime.parse(dateTime) : dateTime.parts;
+
+    return ISODateTime.getISOString(_p);
+  }
+
+  /**
+   * Returns the stored time value in milliseconds since midnight, January 1, 1970 UTC.
+   */
+  valueOf() {
+    if (this.#date === InvalidDate) return Number.NaN;
+
+    return this.#date.valueOf();
+  }
+
+  /**
+   * Retruns ISO date and time string
+   */
+  toString() {
+    return this.#string;
+  }
+
+  /**
+   * Retruns Javascript date object
+   */
+  toDate() {
+    return this.#date;
+  }
+
+  get [Symbol.toStringTag]() {
+    return 'ISODateTime';
+  }
+
+  [Symbol.toPrimitive](hint: 'default'): number;
+  [Symbol.toPrimitive](hint: 'string'): string;
+  [Symbol.toPrimitive](hint: 'number'): number;
+  [Symbol.toPrimitive](hint: string) {
+    if (hint === 'string') return this.toString();
+
+    return this.valueOf();
+  }
+
+  toJSON() {
+    return this.toString();
+  }
+
+  private static getFormatter(isoDatetime: ISODateTime, config?: DateFormatterConfig) {
+    let _format: Partial<Intl.DateTimeFormatOptions> = {};
+
+    if (config?.customFormat?.dateStyle || config?.customFormat?.timeStyle) {
+      _format = {
+        dateStyle: config?.customFormat?.dateStyle,
+        timeStyle: config?.customFormat?.timeStyle,
+      };
+    } else {
+      if (config?.noDate === true && config?.noTime === true) {
+        _format = { ...config.customFormat };
+      } else if (config?.noDate === true && !config?.noTime) {
+        _format = { ...DefaultTimeFormat, ...config.customFormat };
+      } else if (config?.noTime === true && !config.noDate) {
+        _format = { ...DefaultDateFormat, ...config.customFormat };
+      } else {
+        _format = { ...DefaultDateFormat, ...DefaultTimeFormat, ...config?.customFormat };
+      }
+    }
+
+    if (config?.customFormat?.timeZone) _format.timeZone = config.customFormat.timeZone;
+    else if (isoDatetime.parts?.time === undefined) _format.timeZone = 'UTC';
+    else _format.timeZone = DefaultTimezone;
+
+    return new Intl.DateTimeFormat('en', _format);
+  }
+
+  /**
+   * Returns formated date and time string
+   */
+  static format(isoDatetime: string, config?: DateFormatterConfig): string;
+  static format(isoDatetime: ISODateTime, config?: DateFormatterConfig): string;
+  static format(isoDatetime: ISODateTime | string, config?: DateFormatterConfig) {
+    const _isoDatetime = typeof isoDatetime === 'string' ? new ISODateTime(isoDatetime) : isoDatetime;
+
+    const _date = _isoDatetime.toDate();
+    if (_date === InvalidDate) return _isoDatetime.toString();
+
+    const formatter = ISODateTime.getFormatter(_isoDatetime, config);
+    return formatter.format(_date);
+  }
+
+  /**
+   * Returns formated date and time range string
+   */
+  static formatRange(startDate: string, endDate: string, config?: DateFormatterConfig): string;
+  static formatRange(startDate: ISODateTime, endDate: ISODateTime, config?: DateFormatterConfig): string;
+  static formatRange(startDate: ISODateTime | string, endDate: ISODateTime | string, config?: DateFormatterConfig) {
+    const _startISODateTime = typeof startDate === 'string' ? new ISODateTime(startDate) : startDate;
+
+    const _startDate = _startISODateTime.toDate();
+    if (_startDate === InvalidDate) return _startISODateTime.toString();
+
+    const _endISODateTime = typeof endDate === 'string' ? new ISODateTime(endDate) : endDate;
+    const _endDate = _endISODateTime.toDate();
+    if (_endDate === InvalidDate) return _endISODateTime.toString();
+
+    if (_startISODateTime.timezone !== _endISODateTime.timezone) throw 'Start and end dates in different time zones';
+
+    const formatter = ISODateTime.getFormatter(_startISODateTime, config);
+
+    const formatedRange = formatter.formatRange(_startDate, _endDate).replace(/\s/g, ' ');
+
+    // normalize space usage,
+    // `formatRange` uses u+202f to separate the parts in some systems and the standard space in the others
+    return formatedRange.replace(/\s/g, ' ');
+  }
+
+  /**
+   * Returns formated date and time string
+   */
+  format(config?: DateFormatterConfig) {
+    return ISODateTime.format(this, config);
+  }
+
+  /**
+   * Adds milliseconds to the date and returns it as a new ISODateTime object
+   */
+  addMillisecond(milliseconds: number) {
+    return new ISODateTime(this.valueOf() + milliseconds);
+  }
+  /**
+   * Adds seconds to the date and returns it as a new ISODateTime object
+   */
+  addSecond(seconds: number) {
+    return this.addMillisecond(seconds * 1000);
+  }
+  /**
+   * Adds minutes to the date and returns it as a new ISODateTime object
+   */
+  addMinute(minutes: number) {
+    return this.addMillisecond(minutes * 60_000);
+  }
+  /**
+   * Adds hours to the date and returns it as a new ISODateTime object
+   */
+  addHour(hours: number) {
+    return this.addMillisecond(hours * 3_600_000);
+  }
+  /**
+   * Adds days to the date and returns it as a new ISODateTime object
+   */
+  addDay(days: number) {
+    return this.addMillisecond(days * 86_400_000);
+  }
+
+  /**
+   * Returns the start of the previous month as a new ISODateTime object
+   */
+  static getPrevMonthStart(date: ISODateTime) {
+    if (date.parts) {
+      const month = date.parts.date.month ? Number(date.parts.date.month) : 1;
+      const prevMonth = month === 1 ? 12 : month - 1;
+      const year = month === 1 ? (Number(date.parts.date.year) - 1).toString() : date.parts.date.year;
+      const prevParts: ParsedDateTime = {
+        date: {
+          year: year,
+          month: prevMonth.toString().padStart(2, '0'),
+          day: '01',
+        },
+        timezone: date.parts.timezone,
+      };
+
+      return new ISODateTime(ISODateTime.getISOString(prevParts));
+    }
+
+    return date;
+  }
+
+  /**
+   * Returns the start of the previous month as a new ISODateTime object
+   */
+  getPrevMonthStart() {
+    return ISODateTime.getPrevMonthStart(this);
+  }
+
+  /**
+   * Returns the start of the next month as a new ISODateTime object
+   */
+  static getNextMonthStart(date: ISODateTime) {
+    if (date.parts) {
+      const month = date.parts.date.month ? Number(date.parts.date.month) : 1;
+      const nextMonth = (month % 12) + 1;
+      const year = month === 12 ? (Number(date.parts.date.year) + 1).toString() : date.parts.date.year;
+
+      const nextParts: ParsedDateTime = {
+        date: {
+          year: year,
+          month: nextMonth.toString().padStart(2, '0'),
+          day: '01',
+        },
+        timezone: date.parts.timezone,
+      };
+
+      return new ISODateTime(ISODateTime.getISOString(nextParts));
+    }
+
+    return date;
+  }
+
+  /**
+   * Returns the start of the next month as a new ISODateTime object
+   */
+  getNextMonthStart() {
+    return ISODateTime.getNextMonthStart(this);
+  }
+}
+
+interface ISODateParts {
+  year: string;
+  month?: string;
+  day?: string;
+}
+
+interface ISOTimeParts {
+  hours: string;
+  minutes?: string;
+  seconds?: string;
+  milliseconds?: string;
+}
+
+type ISOTimezone = 'Z' | `${'+' | '-'}${string}`;
+
+export interface ParsedDateTime {
+  date: ISODateParts;
+  time?: ISOTimeParts;
+  timezone?: ISOTimezone;
+}
+
+export type DateFormatOptions = Partial<Intl.DateTimeFormatOptions>;
+
+export interface DateFormatterConfig {
+  noDate?: boolean;
+  noTime?: boolean;
+  customFormat?: DateFormatOptions;
+}

package/src/duration/add-durations.ts

@@ -0,0 +1,16 @@
+import { toNumber } from "./to-number";
+
+export function addDuration(left: string, right: string) {
+  const totalDurationInSeconds =
+    toNumber(left, "second") + toNumber(right, "second");
+
+  const hours = Math.floor(totalDurationInSeconds / 3600)
+    .toString()
+    .padStart(2, "0");
+  const minutes = Math.floor((totalDurationInSeconds % 3600) / 60)
+    .toString()
+    .padStart(2, "0");
+  const seconds = (totalDurationInSeconds % 60).toString().padStart(2, "0");
+
+  return `${hours}:${minutes}:${seconds}`;
+}

package/src/duration/index.ts

@@ -0,0 +1,3 @@
+export * from "./is-duration";
+export * from "./to-number";
+export * from "./add-durations";

package/src/duration/is-duration.ts

@@ -0,0 +1,5 @@
+const durationRegExp = /^\d{2}:\d{2}:\d{2}$/;
+
+export function isDuration(duration: string) {
+  return durationRegExp.test(duration);
+}

package/src/duration/to-number.ts

@@ -0,0 +1,18 @@
+import { isDuration } from "./is-duration";
+
+export function toNumber(
+  duration: string,
+  unit: "hour" | "minute" | "second" = "hour",
+) {
+  if (!isDuration(duration)) {
+    console.error(new Error(`Malformed duration value: ${duration}`));
+    return 0;
+  }
+
+  const parts = duration.split(":").map((p) => Number(p));
+
+  if (unit === "minute") return parts[0] * 60 + parts[1] + parts[2] / 60;
+  if (unit === "second") return parts[0] * 3600 + parts[1] * 60 + parts[2];
+
+  return parts[0] + parts[1] / 60 + parts[2] / 3600;
+}

package/src/format/formatter.ts

@@ -0,0 +1,37 @@
+export const dateFormatter = new Intl.DateTimeFormat("en", {
+  dateStyle: "full",
+  timeStyle: "short",
+  timeZone: "America/Vancouver",
+});
+export const formatDate = (date?: Date | null) => {
+  if (date) return dateFormatter.format(date);
+  return "";
+};
+
+const listFormatter = new Intl.ListFormat("en", {
+  style: "long",
+  type: "conjunction",
+});
+
+export const formatList = (list?: string[] | null) => {
+  if (Array.isArray(list)) return listFormatter.format(list);
+  return "";
+};
+
+const numberFormatter = new Intl.NumberFormat("en", {
+  maximumFractionDigits: 2,
+});
+export const formatNumber = (num?: number | null) => {
+  if (num) return numberFormatter.format(num);
+  return "";
+};
+
+const currencyFormatter = new Intl.NumberFormat("en", {
+  style: "currency",
+  currency: "CAD",
+  maximumFractionDigits: 2,
+});
+export const formatCurrency = (num?: number | null) => {
+  if (num) return currencyFormatter.format(num);
+  return "";
+};

package/src/format/index.ts

@@ -0,0 +1,3 @@
+export * from "./formatter";
+export * from "./stringify";
+export * from "./template";