@bccampus/utils 0.1.0

package/README.md

@@ -0,0 +1,8 @@
+# @bccampus/utils
+
+BCcampus' Utility Box
+
+## ToDo
+
+- Write some tests
+- Expected coverage: 80%

package/dist/array/chunk.d.ts

@@ -0,0 +1 @@
+export declare function chunk<T>(arr: T[], size?: number): T[][];

package/dist/array/chunk.js

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

package/dist/array/index.d.ts

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

package/dist/array/index.js

@@ -0,0 +1,4 @@
+import { chunk } from "./chunk.js";
+export {
+  chunk
+};

package/dist/date/index.d.ts

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

package/dist/date/index.js

@@ -0,0 +1,8 @@
+import { DefaultDateFormat, DefaultTimeFormat, DefaultTimezone, ISODateTime, InvalidDate } from "./iso-date-time.js";
+export {
+  DefaultDateFormat,
+  DefaultTimeFormat,
+  DefaultTimezone,
+  ISODateTime,
+  InvalidDate
+};

package/dist/date/iso-date-time.d.ts

@@ -0,0 +1,127 @@
+export declare const InvalidDate: unique symbol;
+export type InvalidDate = typeof InvalidDate;
+export declare const DefaultDateFormat: DateFormatOptions;
+export declare const DefaultTimeFormat: DateFormatOptions;
+export declare const DefaultTimezone = "America/Vancouver";
+/**
+ * Enables storage, retrieval and formating of ISO dates and times
+ * with time zone information.
+ */
+export declare class ISODateTime {
+    #private;
+    constructor();
+    constructor(isoDatetime: number);
+    constructor(isoDatetime: string);
+    /**
+     * Get date and time components
+     */
+    get parts(): ParsedDateTime | undefined;
+    /**
+     * Get timezone
+     */
+    get timezone(): ISOTimezone | "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): ParsedDateTime | undefined;
+    static getISOString(parts?: ParsedDateTime): string;
+    /**
+     * Retruns ISO date and time string
+     */
+    static toString(parsedDateTime: string): string;
+    static toString(parsedDateTime: ISODateTime): string;
+    /**
+     * Returns the stored time value in milliseconds since midnight, January 1, 1970 UTC.
+     */
+    valueOf(): number;
+    /**
+     * Retruns ISO date and time string
+     */
+    toString(): string;
+    /**
+     * Retruns Javascript date object
+     */
+    toDate(): typeof InvalidDate | Date;
+    get [Symbol.toStringTag](): string;
+    [Symbol.toPrimitive](hint: 'default'): number;
+    [Symbol.toPrimitive](hint: 'string'): string;
+    [Symbol.toPrimitive](hint: 'number'): number;
+    toJSON(): string;
+    private static getFormatter;
+    /**
+     * Returns formated date and time string
+     */
+    static format(isoDatetime: string, config?: DateFormatterConfig): string;
+    static format(isoDatetime: ISODateTime, config?: DateFormatterConfig): string;
+    /**
+     * 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;
+    /**
+     * Returns formated date and time string
+     */
+    format(config?: DateFormatterConfig): string;
+    /**
+     * Adds milliseconds to the date and returns it as a new ISODateTime object
+     */
+    addMillisecond(milliseconds: number): ISODateTime;
+    /**
+     * Adds seconds to the date and returns it as a new ISODateTime object
+     */
+    addSecond(seconds: number): ISODateTime;
+    /**
+     * Adds minutes to the date and returns it as a new ISODateTime object
+     */
+    addMinute(minutes: number): ISODateTime;
+    /**
+     * Adds hours to the date and returns it as a new ISODateTime object
+     */
+    addHour(hours: number): ISODateTime;
+    /**
+     * Adds days to the date and returns it as a new ISODateTime object
+     */
+    addDay(days: number): ISODateTime;
+    /**
+     * Returns the start of the previous month as a new ISODateTime object
+     */
+    static getPrevMonthStart(date: ISODateTime): ISODateTime;
+    /**
+     * Returns the start of the previous month as a new ISODateTime object
+     */
+    getPrevMonthStart(): ISODateTime;
+    /**
+     * Returns the start of the next month as a new ISODateTime object
+     */
+    static getNextMonthStart(date: ISODateTime): ISODateTime;
+    /**
+     * Returns the start of the next month as a new ISODateTime object
+     */
+    getNextMonthStart(): ISODateTime;
+}
+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;
+}
+export {};

package/dist/date/iso-date-time.js

@@ -0,0 +1,256 @@
+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})?)$");
+const InvalidDate = /* @__PURE__ */ Symbol("Invalid Date");
+const DefaultDateFormat = {
+  year: "numeric",
+  month: "long",
+  day: "2-digit"
+};
+const DefaultTimeFormat = {
+  hour: "2-digit",
+  minute: "2-digit",
+  timeZoneName: "short"
+};
+const DefaultTimezone = "America/Vancouver";
+class ISODateTime {
+  #parsed;
+  #date;
+  #string;
+  constructor(isoDatetime) {
+    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 = /* @__PURE__ */ 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) {
+    const isoDatetimeParts = isoDatetime.match(isoDateTimeRegEx);
+    if (isoDatetimeParts) {
+      const dateParts = isoDatetimeParts[1] && isoDatetimeParts[1].match(dateRegEx);
+      if (!dateParts) return void 0;
+      const 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];
+      }
+      return parsedDateTime;
+    }
+    return void 0;
+  }
+  static getISOString(parts) {
+    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"}`;
+  }
+  static toString(dateTime) {
+    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) {
+    if (hint === "string") return this.toString();
+    return this.valueOf();
+  }
+  toJSON() {
+    return this.toString();
+  }
+  static getFormatter(isoDatetime, config) {
+    let _format = {};
+    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 === void 0) _format.timeZone = "UTC";
+    else _format.timeZone = DefaultTimezone;
+    return new Intl.DateTimeFormat("en", _format);
+  }
+  static format(isoDatetime, config) {
+    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);
+  }
+  static formatRange(startDate, endDate, config) {
+    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, " ");
+    return formatedRange.replace(/\s/g, " ");
+  }
+  /**
+   * Returns formated date and time string
+   */
+  format(config) {
+    return ISODateTime.format(this, config);
+  }
+  /**
+   * Adds milliseconds to the date and returns it as a new ISODateTime object
+   */
+  addMillisecond(milliseconds) {
+    return new ISODateTime(this.valueOf() + milliseconds);
+  }
+  /**
+   * Adds seconds to the date and returns it as a new ISODateTime object
+   */
+  addSecond(seconds) {
+    return this.addMillisecond(seconds * 1e3);
+  }
+  /**
+   * Adds minutes to the date and returns it as a new ISODateTime object
+   */
+  addMinute(minutes) {
+    return this.addMillisecond(minutes * 6e4);
+  }
+  /**
+   * Adds hours to the date and returns it as a new ISODateTime object
+   */
+  addHour(hours) {
+    return this.addMillisecond(hours * 36e5);
+  }
+  /**
+   * Adds days to the date and returns it as a new ISODateTime object
+   */
+  addDay(days) {
+    return this.addMillisecond(days * 864e5);
+  }
+  /**
+   * Returns the start of the previous month as a new ISODateTime object
+   */
+  static getPrevMonthStart(date) {
+    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 = {
+        date: {
+          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) {
+    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 = {
+        date: {
+          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);
+  }
+}
+export {
+  DefaultDateFormat,
+  DefaultTimeFormat,
+  DefaultTimezone,
+  ISODateTime,
+  InvalidDate
+};

package/dist/duration/add-durations.d.ts

@@ -0,0 +1 @@
+export declare function addDuration(left: string, right: string): string;

package/dist/duration/add-durations.js

@@ -0,0 +1,12 @@
+import "./is-duration.js";
+import { toNumber } from "./to-number.js";
+function addDuration(left, right) {
+  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}`;
+}
+export {
+  addDuration
+};

package/dist/duration/index.d.ts

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

package/dist/duration/index.js

@@ -0,0 +1,8 @@
+import { isDuration } from "./is-duration.js";
+import { toNumber } from "./to-number.js";
+import { addDuration } from "./add-durations.js";
+export {
+  addDuration,
+  isDuration,
+  toNumber
+};

package/dist/duration/is-duration.d.ts

@@ -0,0 +1 @@
+export declare function isDuration(duration: string): boolean;

package/dist/duration/is-duration.js

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

package/dist/duration/to-number.d.ts

@@ -0,0 +1 @@
+export declare function toNumber(duration: string, unit?: "hour" | "minute" | "second"): number;

package/dist/duration/to-number.js

@@ -0,0 +1,14 @@
+import { isDuration } from "./is-duration.js";
+function toNumber(duration, unit = "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;
+}
+export {
+  toNumber
+};

package/dist/format/formatter.d.ts

@@ -0,0 +1,5 @@
+export declare const dateFormatter: Intl.DateTimeFormat;
+export declare const formatDate: (date?: Date | null) => string;
+export declare const formatList: (list?: string[] | null) => string;
+export declare const formatNumber: (num?: number | null) => string;
+export declare const formatCurrency: (num?: number | null) => string;

package/dist/format/formatter.js

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

package/dist/format/index.d.ts

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

package/dist/format/index.js

@@ -0,0 +1,13 @@
+import { dateFormatter, formatCurrency, formatDate, formatList, formatNumber } from "./formatter.js";
+import { stringify } from "./stringify.js";
+import { template, templateObject } from "./template.js";
+export {
+  dateFormatter,
+  formatCurrency,
+  formatDate,
+  formatList,
+  formatNumber,
+  stringify,
+  template,
+  templateObject
+};

package/dist/format/stringify.d.ts

@@ -0,0 +1,38 @@
+export interface StringifyValueOptions {
+    /**
+     * String value to return when the value undefined or null.
+     *
+     * Default Unicode NUL(\u0000) character,
+     * guarantees that the function always returns a string and
+     * allows to distinguish invalid values from an empty string.
+     *
+     * ```ts
+     *   const stringValue = stringify(value);
+     *   console.log(stringValue !== '\u0000' ? 'Invalid' : stringValue)
+     * ```
+     */
+    invalidValueString?: string;
+    /**
+     * `stringify` prepends type info to the return value.
+     */
+    withTypeInfo?: boolean;
+    /**
+     * If the value is a function that doesn't expect an argument,
+     * `stringify` calls the function recursively.
+     */
+    callFunctions?: boolean;
+    /**
+     * `stringify` adds indentation and new lines to object return values.
+     */
+    prettyObjects?: boolean;
+    /**
+     * `stringify` returns verbose value.
+     */
+    verbose?: boolean;
+}
+/**
+ * Returns string representation of the value;
+ *
+ * If the valid is null or undefined, returns `options.invalidValueString`.
+ */
+export declare const stringify: (value: unknown, options?: StringifyValueOptions) => string;

package/dist/format/stringify.js

@@ -0,0 +1,42 @@
+import { formatNumber, formatList, dateFormatter } from "./formatter.js";
+import { ISODateTime } from "../date/iso-date-time.js";
+const stringify = (value, options) => {
+  const _options = {
+    invalidValueString: "\0",
+    // Unicode NUL
+    withTypeInfo: options?.verbose,
+    prettyObjects: options?.verbose,
+    ...options
+  };
+  if (value === void 0)
+    return _options.withTypeInfo ? "[undefined]" : _options.invalidValueString;
+  if (value === null)
+    return _options.withTypeInfo ? "[null]" : _options.invalidValueString;
+  if (typeof value === "string")
+    return `${_options.withTypeInfo ? "[string] " : ""}${value}`;
+  if (typeof value === "number")
+    return `${_options.withTypeInfo ? "[number] " : ""}${formatNumber(value)}`;
+  if (typeof value === "bigint")
+    return `${_options.withTypeInfo ? "[bigint] " : ""}${value}`;
+  if (typeof value === "boolean")
+    return `${_options.withTypeInfo ? "[boolean] " : ""}${value}`;
+  if (typeof value === "object") {
+    if (Array.isArray(value)) {
+      const stringfiedValue = value.map((el) => stringify(el, _options));
+      return `${_options.withTypeInfo ? "[array] " : ""}${_options.verbose ? stringfiedValue.join(", ") : formatList(stringfiedValue)}`;
+    }
+    if (value instanceof Date)
+      return `${_options.withTypeInfo ? "[date] " : ""}${dateFormatter.format(value)}`;
+    if (value instanceof ISODateTime)
+      return `${_options.withTypeInfo ? "[date] " : ""}${value.format()}`;
+    return `${_options.withTypeInfo ? "[object] " : ""}${JSON.stringify(value, null, _options.prettyObjects ? 2 : void 0)}`;
+  }
+  if (typeof value === "function")
+    return `${_options.withTypeInfo ? "[function] " : ""}${_options.callFunctions && value.length === 0 ? stringify(value(), _options) : value.toString()}`;
+  if (typeof value === "symbol")
+    return `${_options.withTypeInfo ? "[symbol] " : ""}${value.toString()}`;
+  return _options.invalidValueString;
+};
+export {
+  stringify
+};

package/dist/format/template.d.ts

@@ -0,0 +1,6 @@
+type TemplateVarValue = unknown | undefined | null;
+export type TemplateVar = TemplateVarValue | (() => TemplateVarValue);
+export type TemplateVars = Record<string, TemplateVar>;
+export declare const template: (text: string, templateVars: TemplateVars) => string;
+export declare const templateObject: <T extends object>(obj: T, templateVars: TemplateVars) => T;
+export {};