@8ms/helpers 3.1.0 → 3.2.0

package/dist/date/_shared/calculation.mjs

@@ -0,0 +1,257 @@
+import { DateTime, Interval } from "luxon";
+//#region src/date/_shared/calculation.ts
+/**
+* Return unix timestamp in seconds.
+*/
+const getUnix = (input) => {
+	return getLuxonDate(input).toUnixInteger();
+};
+/**
+* Assume the input is always UTC.
+*
+* If it's not UTC, it needs to be converted to UTC before being used.
+*/
+const getLuxonDate = (input, setMidnight) => {
+	let instance = DateTime.now().toUTC();
+	if (input) {
+		if (input instanceof Date) instance = DateTime.fromJSDate(input, { zone: "utc" });
+		else if (input instanceof DateTime) instance = input.toUTC();
+		else if ("number" === typeof input) {
+			if (input >= 19000101 && input <= 99991231) {
+				const dateStr = input.toString();
+				const year = parseInt(dateStr.substring(0, 4));
+				const month = parseInt(dateStr.substring(4, 6));
+				const day = parseInt(dateStr.substring(6, 8));
+				instance = DateTime.fromObject({
+					year,
+					month,
+					day
+				}, { zone: "utc" });
+			} else if (input < 1e10) instance = DateTime.fromSeconds(input, { zone: "utc" });
+			else instance = DateTime.fromMillis(input, { zone: "utc" });
+		} else {
+			const inputString = input.toString().toLowerCase();
+			if (/^\d+$/.test(inputString)) instance = getLuxonDate(Number(inputString));
+			else instance = DateTime.fromISO(inputString, { zone: "utc" });
+			if (!instance.isValid) {
+				const len = inputString.length;
+				if (23 === len) instance = DateTime.fromFormat(inputString, "yyyy-MM-dd HH:mm:ss.SSS", { zone: "utc" });
+				else if (19 === len) instance = DateTime.fromFormat(inputString, "yyyy-MM-dd HH:mm:ss", { zone: "utc" });
+				else {
+					instance = DateTime.fromFormat(inputString, "yyyy MMMM dd", { zone: "utc" });
+					if (!instance.isValid) instance = DateTime.fromFormat(inputString, "yyyy-MMMM-dd", { zone: "utc" });
+				}
+			}
+		}
+	}
+	instance = instance.setZone("utc", { keepLocalTime: false });
+	if (setMidnight) instance = instance.set({
+		hour: 0,
+		minute: 0,
+		second: 0,
+		millisecond: 0
+	});
+	return instance;
+};
+const isMonday = (input) => {
+	return getLuxonDate(input).weekday === 1;
+};
+const isTuesday = (input) => {
+	return getLuxonDate(input).weekday === 2;
+};
+const isWednesday = (input) => {
+	return getLuxonDate(input).weekday === 3;
+};
+const isThursday = (input) => {
+	return getLuxonDate(input).weekday === 4;
+};
+const isFriday = (input) => {
+	return getLuxonDate(input).weekday === 6;
+};
+const isSaturday = (input) => {
+	return getLuxonDate(input).weekday === 6;
+};
+const isSunday = (input) => {
+	return getLuxonDate(input).weekday === 7;
+};
+/**
+* Determines if a given date falls on a weekend.
+*
+* This function checks whether the day of the week for the provided input corresponds
+* to Saturday or Sunday, where weekday values of 6 and 7 represent Saturday and Sunday, respectively.
+*/
+const isWeekend = (input) => {
+	const luxonDate = getLuxonDate(input);
+	return 6 === luxonDate.weekday || 7 === luxonDate.weekday;
+};
+/**
+* Determines whether a given unix timestamp is older than the provided threshold, in seconds.
+*
+* Example: 50 minutes, would be 50 * 60.
+*/
+const isStale = (timeout, threshold) => {
+	return getUnix() - timeout > threshold;
+};
+/**
+* Calculates the difference in minutes between two provided dates.
+*/
+const differenceInMinutes = (start, end) => {
+	const startDate = getLuxonDate(start);
+	return getLuxonDate(end).diff(startDate, "minutes").minutes;
+};
+/**
+* Calculates the difference in business days between two dates.
+* Business days are considered as weekdays (Monday to Friday).
+*/
+const differenceInBusinessDays = (start, end) => {
+	const startDate = getLuxonDate(start);
+	const endDate = getLuxonDate(end);
+	let businessDays = 0;
+	let current = startDate.startOf("day");
+	while (current < endDate.startOf("day")) {
+		if (current.weekday <= 5) businessDays++;
+		current = current.plus({ days: 1 });
+	}
+	return businessDays;
+};
+/**
+* Similar to date-fns' eachDayOfInterval, however the timezone messes this function up.
+* https://date-fns.org/v2.28.0/docs/eachDayOfInterval
+* https://www.gov.uk/when-do-the-clocks-change
+*/
+const getDatesBetween = (start, end) => {
+	const startInstance = getLuxonDate(start);
+	const endInstance = getLuxonDate(end);
+	return Interval.fromDateTimes(startInstance.startOf("day"), endInstance.endOf("day")).splitBy({ day: 1 }).map((d) => d.start);
+};
+/**
+* Get an array of DateTime objects representing the 1st of each month between start and end dates.
+*/
+const getMonthsBetween = (start, end) => {
+	const months = [];
+	const endDate = getLuxonDate(end).startOf("month");
+	let current = getLuxonDate(start).startOf("month");
+	while (current <= endDate) {
+		months.push(current);
+		current = current.plus({ months: 1 });
+	}
+	return months;
+};
+/**
+* If a given date is beyond the maximum, return the maximum.
+*/
+const getMax = (input, max) => {
+	return input > max ? max : input;
+};
+/**
+* If a given date is before the minimum, return the minimum.
+*/
+const getMin = (input, min) => {
+	return input < min ? min : input;
+};
+/**
+* Retrieve the closest last Monday relative to the input or today.
+* 0 weeksAgo - Tuesday (10th), return Monday (8th)
+* 1 weeksAgo - Tuesday (10th), return Monday (1st)
+*/
+const getMonday = (input, weeksAgo) => {
+	let instance = getLuxonDate(input);
+	if ("Mon" !== instance.toFormat("EEE")) {
+		const isoDay = Number(instance.toFormat("E")) - 1;
+		instance = instance.minus({ days: isoDay });
+	}
+	instance = instance.minus({ weeks: weeksAgo ?? 0 });
+	return instance;
+};
+/**
+* Retrieve the closest last Sunday relative to the input or today.
+* 0 weeksAgo - Tuesday (17th), return Sunday (14th)
+* 1 weeksAgo - Tuesday (17th), return Monday (7th)
+*/
+const getSunday = (input, weeksAgo) => {
+	let instance = getLuxonDate(input);
+	if ("Sun" !== instance.toFormat("EEE")) {
+		const isoDay = Number(instance.toFormat("E"));
+		instance = instance.minus({ days: isoDay });
+	}
+	instance = instance.minus({ weeks: weeksAgo ?? 0 });
+	return instance;
+};
+/**
+* Return an object of start/end predefined date of Last Week.
+* Creating a date from scratch (no user input), thus needs to be London time.
+*/
+const getLastWeek = () => {
+	return {
+		end: getMonday(void 0, 0),
+		start: getSunday(void 0, 1)
+	};
+};
+/**
+* Return an object of start/end predefined date of This Week.
+* Creating a date from scratch (no user input), thus needs to be London time.
+*/
+const getThisWeek = () => {
+	return {
+		end: getMonday(void 0, 0),
+		start: getSunday(void 0, -1)
+	};
+};
+/**
+* Return an object of start/end predefined date of Two Weeks Ago.
+* Creating a date from scratch (no user input), thus needs to be London time.
+*/
+const getTwoWeeksAgo = () => {
+	return {
+		end: getMonday(void 0, 1),
+		start: getSunday(void 0, 2)
+	};
+};
+/**
+* Shortcut to get today's date.
+* Creating a date from scratch (no user input), thus needs to be London time.
+*/
+const getToday = (setMidnight) => {
+	return getLuxonDate(void 0, setMidnight);
+};
+/**
+* From a given input, move the date back X weeksAgo
+*/
+const getWeeksAgo = (input, weeksAgo) => {
+	let instance = getLuxonDate(input);
+	instance = instance.plus({ weeks: weeksAgo });
+	return instance;
+};
+/**
+* Shortcut to get yesterday's date.
+* Creating a date from scratch (no user input), thus needs to be London time.
+*/
+const getYesterday = (input) => {
+	let instance = getLuxonDate(input);
+	instance = instance.minus({ days: 1 });
+	return instance;
+};
+/**
+* Check to see if a given timeframe is This Week.
+*/
+const isThisWeek = (start, end) => {
+	const inputWeek = {
+		start: getLuxonDate(start),
+		end: getLuxonDate(end)
+	};
+	const thisWeek = getThisWeek();
+	return inputWeek.start.hasSame(thisWeek.start, "day") && inputWeek.end.hasSame(thisWeek.end, "day");
+};
+/**
+* Check to see if a given timeframe is Last Week.
+*/
+const isLastWeek = (start, end) => {
+	const inputWeek = {
+		start: getLuxonDate(start),
+		end: getLuxonDate(end)
+	};
+	const lastWeek = getLastWeek();
+	return inputWeek.start.hasSame(lastWeek.start, "day") && inputWeek.end.hasSame(lastWeek.end, "day");
+};
+//#endregion
+export { differenceInBusinessDays, differenceInMinutes, getDatesBetween, getLastWeek, getLuxonDate, getMax, getMin, getMonday, getMonthsBetween, getSunday, getThisWeek, getToday, getTwoWeeksAgo, getUnix, getWeeksAgo, getYesterday, isFriday, isLastWeek, isMonday, isSaturday, isStale, isSunday, isThisWeek, isThursday, isTuesday, isWednesday, isWeekend };

package/dist/date/_shared/date.cjs

@@ -0,0 +1,27 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/date/_shared/date.ts
+const defaultDate = "1901-01-01";
+const defaultDateNumber = 19010101;
+const defaultDateTime = "1901-01-01 00:00:00";
+/**
+* Used by Google Ads API.
+*/
+const month = {
+	JANUARY: "JANUARY",
+	FEBRUARY: "FEBRUARY",
+	MARCH: "MARCH",
+	APRIL: "APRIL",
+	MAY: "MAY",
+	JUNE: "JUNE",
+	JULY: "JULY",
+	AUGUST: "AUGUST",
+	SEPTEMBER: "SEPTEMBER",
+	OCTOBER: "OCTOBER",
+	NOVEMBER: "NOVEMBER",
+	DECEMBER: "DECEMBER"
+};
+//#endregion
+exports.defaultDate = defaultDate;
+exports.defaultDateNumber = defaultDateNumber;
+exports.defaultDateTime = defaultDateTime;
+exports.month = month;

package/dist/date/_shared/date.d.cts

@@ -0,0 +1,50 @@
+import { DateTime } from "luxon";
+//#region src/date/_shared/date.d.ts
+export type InputDate = Date | DateTime | string | number;
+export type FinancialWeek = {
+  end: DateTime;
+  start: DateTime;
+  weekNumber: number;
+  year: number;
+};
+/**
+ * A timeframe has a start and an end date.
+ */
+export type DateRangeNumber = {
+  start: number;
+  end: number;
+};
+export type DateRangeLuxon = {
+  start: DateTime;
+  end: DateTime;
+};
+export type DateRangeString = {
+  start: string;
+  end: string;
+};
+export type DateRangeInput = {
+  start: InputDate;
+  end: InputDate;
+};
+export declare const defaultDate: "1901-01-01";
+export declare const defaultDateNumber: 19010101;
+export declare const defaultDateTime: "1901-01-01 00:00:00";
+/**
+ * Used by Google Ads API.
+ */
+export declare const month: {
+  readonly JANUARY: "JANUARY";
+  readonly FEBRUARY: "FEBRUARY";
+  readonly MARCH: "MARCH";
+  readonly APRIL: "APRIL";
+  readonly MAY: "MAY";
+  readonly JUNE: "JUNE";
+  readonly JULY: "JULY";
+  readonly AUGUST: "AUGUST";
+  readonly SEPTEMBER: "SEPTEMBER";
+  readonly OCTOBER: "OCTOBER";
+  readonly NOVEMBER: "NOVEMBER";
+  readonly DECEMBER: "DECEMBER";
+};
+export type Month = typeof month[keyof typeof month];
+//#endregion

package/dist/date/_shared/date.d.mts

@@ -0,0 +1,50 @@
+import { DateTime } from "luxon";
+//#region src/date/_shared/date.d.ts
+export type InputDate = Date | DateTime | string | number;
+export type FinancialWeek = {
+  end: DateTime;
+  start: DateTime;
+  weekNumber: number;
+  year: number;
+};
+/**
+ * A timeframe has a start and an end date.
+ */
+export type DateRangeNumber = {
+  start: number;
+  end: number;
+};
+export type DateRangeLuxon = {
+  start: DateTime;
+  end: DateTime;
+};
+export type DateRangeString = {
+  start: string;
+  end: string;
+};
+export type DateRangeInput = {
+  start: InputDate;
+  end: InputDate;
+};
+export declare const defaultDate: "1901-01-01";
+export declare const defaultDateNumber: 19010101;
+export declare const defaultDateTime: "1901-01-01 00:00:00";
+/**
+ * Used by Google Ads API.
+ */
+export declare const month: {
+  readonly JANUARY: "JANUARY";
+  readonly FEBRUARY: "FEBRUARY";
+  readonly MARCH: "MARCH";
+  readonly APRIL: "APRIL";
+  readonly MAY: "MAY";
+  readonly JUNE: "JUNE";
+  readonly JULY: "JULY";
+  readonly AUGUST: "AUGUST";
+  readonly SEPTEMBER: "SEPTEMBER";
+  readonly OCTOBER: "OCTOBER";
+  readonly NOVEMBER: "NOVEMBER";
+  readonly DECEMBER: "DECEMBER";
+};
+export type Month = typeof month[keyof typeof month];
+//#endregion

package/dist/date/_shared/date.mjs

@@ -0,0 +1,23 @@
+//#region src/date/_shared/date.ts
+const defaultDate = "1901-01-01";
+const defaultDateNumber = 19010101;
+const defaultDateTime = "1901-01-01 00:00:00";
+/**
+* Used by Google Ads API.
+*/
+const month = {
+	JANUARY: "JANUARY",
+	FEBRUARY: "FEBRUARY",
+	MARCH: "MARCH",
+	APRIL: "APRIL",
+	MAY: "MAY",
+	JUNE: "JUNE",
+	JULY: "JULY",
+	AUGUST: "AUGUST",
+	SEPTEMBER: "SEPTEMBER",
+	OCTOBER: "OCTOBER",
+	NOVEMBER: "NOVEMBER",
+	DECEMBER: "DECEMBER"
+};
+//#endregion
+export { defaultDate, defaultDateNumber, defaultDateTime, month };

package/dist/date/_shared/financialYear.cjs

@@ -0,0 +1,60 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_date__shared_calculation = require("./calculation.cjs");
+let luxon = require("luxon");
+//#region src/date/_shared/financialYear.ts
+/**
+* Get the financial year based on an optional year.
+*/
+const getFinancialYear = (year) => {
+	let financialYear = year ?? 0;
+	if ("undefined" === typeof year) {
+		const todayInstance = require_date__shared_calculation.getToday();
+		if (todayInstance < require_date__shared_calculation.getLuxonDate(`${todayInstance.toFormat("yyyy")}-04-01`)) financialYear = Number(todayInstance.toFormat("yyyy")) - 1;
+		else financialYear = Number(todayInstance.toFormat("yyyy"));
+	}
+	let yearStartInstance = require_date__shared_calculation.getLuxonDate(`${financialYear}-04-01`);
+	if ("Mon" !== yearStartInstance.toFormat("EEE")) {
+		const daysToSubtract = Number(yearStartInstance.toFormat("E")) - 1;
+		yearStartInstance = yearStartInstance.minus({ days: daysToSubtract });
+	}
+	let yearEndInstance = require_date__shared_calculation.getLuxonDate(`${financialYear + 1}-03-31`);
+	if ("Sun" !== yearEndInstance.toFormat("EEE")) {
+		const daysToAdd = 7 - Number(yearEndInstance.toFormat("E"));
+		yearEndInstance = yearEndInstance.plus({ days: daysToAdd });
+	}
+	return {
+		end: yearEndInstance,
+		start: yearStartInstance
+	};
+};
+/**
+* Return the current financial year up to today.
+*/
+const getFinancialYearToDate = () => {
+	return {
+		end: require_date__shared_calculation.getToday(),
+		start: getFinancialYear().start
+	};
+};
+/**
+* Return the current financial year up to yesterday.
+* Timezone should always be London based
+*/
+const getFinancialYearToYesterday = () => {
+	return {
+		end: require_date__shared_calculation.getYesterday(),
+		start: getFinancialYear().start
+	};
+};
+/**
+* Get the current financial year.
+*/
+const getFinancialYearWeeks = (year) => {
+	const financialYear = getFinancialYear(year);
+	return luxon.Interval.fromDateTimes(financialYear.start, financialYear.end).splitBy({ weeks: 1 });
+};
+//#endregion
+exports.getFinancialYear = getFinancialYear;
+exports.getFinancialYearToDate = getFinancialYearToDate;
+exports.getFinancialYearToYesterday = getFinancialYearToYesterday;
+exports.getFinancialYearWeeks = getFinancialYearWeeks;

package/dist/date/_shared/financialYear.d.cts

@@ -0,0 +1,21 @@
+import { DateRangeLuxon } from "./date.cjs";
+import { Interval } from "luxon";
+//#region src/date/_shared/financialYear.d.ts
+/**
+ * Get the financial year based on an optional year.
+ */
+export declare const getFinancialYear: (year?: number) => DateRangeLuxon;
+/**
+ * Return the current financial year up to today.
+ */
+export declare const getFinancialYearToDate: () => DateRangeLuxon;
+/**
+ * Return the current financial year up to yesterday.
+ * Timezone should always be London based
+ */
+export declare const getFinancialYearToYesterday: () => DateRangeLuxon;
+/**
+ * Get the current financial year.
+ */
+export declare const getFinancialYearWeeks: (year?: number) => Interval<boolean>[];
+//#endregion

package/dist/date/_shared/financialYear.d.mts

@@ -0,0 +1,21 @@
+import { DateRangeLuxon } from "./date.mjs";
+import { Interval } from "luxon";
+//#region src/date/_shared/financialYear.d.ts
+/**
+ * Get the financial year based on an optional year.
+ */
+export declare const getFinancialYear: (year?: number) => DateRangeLuxon;
+/**
+ * Return the current financial year up to today.
+ */
+export declare const getFinancialYearToDate: () => DateRangeLuxon;
+/**
+ * Return the current financial year up to yesterday.
+ * Timezone should always be London based
+ */
+export declare const getFinancialYearToYesterday: () => DateRangeLuxon;
+/**
+ * Get the current financial year.
+ */
+export declare const getFinancialYearWeeks: (year?: number) => Interval<boolean>[];
+//#endregion

package/dist/date/_shared/financialYear.mjs

@@ -0,0 +1,56 @@
+import { getLuxonDate, getToday, getYesterday } from "./calculation.mjs";
+import { Interval } from "luxon";
+//#region src/date/_shared/financialYear.ts
+/**
+* Get the financial year based on an optional year.
+*/
+const getFinancialYear = (year) => {
+	let financialYear = year ?? 0;
+	if ("undefined" === typeof year) {
+		const todayInstance = getToday();
+		if (todayInstance < getLuxonDate(`${todayInstance.toFormat("yyyy")}-04-01`)) financialYear = Number(todayInstance.toFormat("yyyy")) - 1;
+		else financialYear = Number(todayInstance.toFormat("yyyy"));
+	}
+	let yearStartInstance = getLuxonDate(`${financialYear}-04-01`);
+	if ("Mon" !== yearStartInstance.toFormat("EEE")) {
+		const daysToSubtract = Number(yearStartInstance.toFormat("E")) - 1;
+		yearStartInstance = yearStartInstance.minus({ days: daysToSubtract });
+	}
+	let yearEndInstance = getLuxonDate(`${financialYear + 1}-03-31`);
+	if ("Sun" !== yearEndInstance.toFormat("EEE")) {
+		const daysToAdd = 7 - Number(yearEndInstance.toFormat("E"));
+		yearEndInstance = yearEndInstance.plus({ days: daysToAdd });
+	}
+	return {
+		end: yearEndInstance,
+		start: yearStartInstance
+	};
+};
+/**
+* Return the current financial year up to today.
+*/
+const getFinancialYearToDate = () => {
+	return {
+		end: getToday(),
+		start: getFinancialYear().start
+	};
+};
+/**
+* Return the current financial year up to yesterday.
+* Timezone should always be London based
+*/
+const getFinancialYearToYesterday = () => {
+	return {
+		end: getYesterday(),
+		start: getFinancialYear().start
+	};
+};
+/**
+* Get the current financial year.
+*/
+const getFinancialYearWeeks = (year) => {
+	const financialYear = getFinancialYear(year);
+	return Interval.fromDateTimes(financialYear.start, financialYear.end).splitBy({ weeks: 1 });
+};
+//#endregion
+export { getFinancialYear, getFinancialYearToDate, getFinancialYearToYesterday, getFinancialYearWeeks };