toolbox-x 1.0.0

package/dist/css-colors-DfUW3nTR.mjs

@@ -0,0 +1,180 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+//#region src/colors/css-colors.ts
+/** List of CSS Colors as Object with color name as key and hex code as value */
+const CSS_COLORS = /* @__PURE__ */ Object.freeze({
+	black: "#000000",
+	silver: "#C0C0C0",
+	gray: "#808080",
+	white: "#FFFFFF",
+	maroon: "#800000",
+	red: "#FF0000",
+	purple: "#800080",
+	fuchsia: "#FF00FF",
+	green: "#008000",
+	lime: "#00FF00",
+	olive: "#808000",
+	yellow: "#FFFF00",
+	navy: "#000080",
+	blue: "#0000FF",
+	teal: "#008080",
+	aqua: "#00FFFF",
+	aliceblue: "#F0F8FF",
+	antiquewhite: "#FAEBD7",
+	aquamarine: "#7FFFD4",
+	azure: "#F0FFFF",
+	beige: "#F5F5DC",
+	bisque: "#FFE4C4",
+	blanchedalmond: "#FFEBCD",
+	blueviolet: "#8A2BE2",
+	brown: "#A52A2A",
+	burlywood: "#DEB887",
+	cadetblue: "#5F9EA0",
+	chartreuse: "#7FFF00",
+	chocolate: "#D2691E",
+	coral: "#FF7F50",
+	cornflowerblue: "#6495ED",
+	cornsilk: "#FFF8DC",
+	crimson: "#DC143C",
+	cyan: "#00FFFF",
+	darkblue: "#00008B",
+	darkcyan: "#008B8B",
+	darkgoldenrod: "#B8860B",
+	darkgray: "#A9A9A9",
+	darkgreen: "#006400",
+	darkgrey: "#A9A9A9",
+	darkkhaki: "#BDB76B",
+	darkmagenta: "#8B008B",
+	darkolivegreen: "#556B2F",
+	darkorange: "#FF8C00",
+	darkorchid: "#9932CC",
+	darkred: "#8B0000",
+	darksalmon: "#E9967A",
+	darkseagreen: "#8FBC8F",
+	darkslateblue: "#483D8B",
+	darkslategray: "#2F4F4F",
+	darkslategrey: "#2F4F4F",
+	darkturquoise: "#00CED1",
+	darkviolet: "#9400D3",
+	deeppink: "#FF1493",
+	deepskyblue: "#00BFFF",
+	dimgray: "#696969",
+	dimgrey: "#696969",
+	dodgerblue: "#1E90FF",
+	firebrick: "#B22222",
+	floralwhite: "#FFFAF0",
+	forestgreen: "#228B22",
+	gainsboro: "#DCDCDC",
+	ghostwhite: "#F8F8FF",
+	gold: "#FFD700",
+	goldenrod: "#DAA520",
+	greenyellow: "#ADFF2F",
+	grey: "#808080",
+	honeydew: "#F0FFF0",
+	hotpink: "#FF69B4",
+	indianred: "#CD5C5C",
+	indigo: "#4B0082",
+	ivory: "#FFFFF0",
+	khaki: "#F0E68C",
+	lavender: "#E6E6FA",
+	lavenderblush: "#FFF0F5",
+	lawngreen: "#7CFC00",
+	lemonchiffon: "#FFFACD",
+	lightblue: "#ADD8E6",
+	lightcoral: "#F08080",
+	lightcyan: "#E0FFFF",
+	lightgoldenrodyellow: "#FAFAD2",
+	lightgray: "#D3D3D3",
+	lightgreen: "#90EE90",
+	lightgrey: "#D3D3D3",
+	lightpink: "#FFB6C1",
+	lightsalmon: "#FFA07A",
+	lightseagreen: "#20B2AA",
+	lightskyblue: "#87CEFA",
+	lightslategray: "#778899",
+	lightslategrey: "#778899",
+	lightsteelblue: "#B0C4DE",
+	lightyellow: "#FFFFE0",
+	limegreen: "#32CD32",
+	linen: "#FAF0E6",
+	magenta: "#FF00FF",
+	mediumaquamarine: "#66CDAA",
+	mediumblue: "#0000CD",
+	mediumorchid: "#BA55D3",
+	mediumpurple: "#9370DB",
+	mediumseagreen: "#3CB371",
+	mediumslateblue: "#7B68EE",
+	mediumspringgreen: "#00FA9A",
+	mediumturquoise: "#48D1CC",
+	mediumvioletred: "#C71585",
+	midnightblue: "#191970",
+	mintcream: "#F5FFFA",
+	mistyrose: "#FFE4E1",
+	moccasin: "#FFE4B5",
+	navajowhite: "#FFDEAD",
+	oldlace: "#FDF5E6",
+	olivedrab: "#6B8E23",
+	orange: "#FFA500",
+	orangered: "#FF4500",
+	orchid: "#DA70D6",
+	palegoldenrod: "#EEE8AA",
+	palegreen: "#98FB98",
+	paleturquoise: "#AFEEEE",
+	palevioletred: "#DB7093",
+	papayawhip: "#FFEFD5",
+	peachpuff: "#FFDAB9",
+	peru: "#CD853F",
+	pink: "#FFC0CB",
+	plum: "#DDA0DD",
+	powderblue: "#B0E0E6",
+	rebeccapurple: "#663399",
+	rosybrown: "#BC8F8F",
+	royalblue: "#4169E1",
+	saddlebrown: "#8B4513",
+	salmon: "#FA8072",
+	sandybrown: "#F4A460",
+	seagreen: "#2E8B57",
+	seashell: "#FFF5EE",
+	sienna: "#A0522D",
+	skyblue: "#87CEEB",
+	slateblue: "#6A5ACD",
+	slategray: "#708090",
+	slategrey: "#708090",
+	snow: "#FFFAFA",
+	springgreen: "#00FF7F",
+	steelblue: "#4682B4",
+	tan: "#D2B48C",
+	thistle: "#D8BFD8",
+	tomato: "#FF6347",
+	transparent: "#00000000",
+	turquoise: "#40E0D0",
+	violet: "#EE82EE",
+	wheat: "#F5DEB3",
+	whitesmoke: "#F5F5F5",
+	yellowgreen: "#9ACD32",
+	grape: "#CC5DE8",
+	dark: "#3B3B3B",
+	volcano: "#FA541C",
+	geekblue: "#2F54EB",
+	success: "#4CAF50",
+	info: "#2196F3",
+	warning: "#FF9800",
+	error: "#F44336"
+});
+
+//#endregion
+export { CSS_COLORS as t };

package/dist/date.cjs

@@ -0,0 +1,332 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primitives = require('./primitives-B26uZolQ.cjs');
+const require_timezone = require('./timezone-Beh9IGpw.cjs');
+const require_specials = require('./specials-DzLr1ZgU.cjs');
+const require_utilities = require('./utilities-CLUmdQeV.cjs');
+const require_guards = require('./guards-Efhp1mNy.cjs');
+const require_parse = require('./parse-2ubxXZRp.cjs');
+
+//#region src/date/utils.ts
+/**
+* * Extracts the hour and minute from a time string in `HH:MM` or `-HH:MM` format.
+*
+* @param time - The time string to extract from.
+* @return The extracted hour and minute as number tuple.
+*/
+function extractHourMinute(time) {
+	const [hour, minute] = time.split(":").map(Number);
+	return [hour, minute];
+}
+/**
+* * Converts a time string `HH:MM` or `-HH:MM` into total minutes from `00:00`.
+*
+* @param time - The time in `HH:MM` or `-HH:MM` format.
+* @returns The total minutes elapsed since `00:00`.
+*/
+function getTotalMinutes(time) {
+	const isNegative = time.startsWith("-");
+	const [h, m] = extractHourMinute(isNegative ? time.slice(1) : time);
+	const total = h * 60 + m;
+	return isNegative ? -total : total;
+}
+/**
+* * Returns the current date and time as `Date` object.
+* - All the methods and properties of `new Date()` are accessible.
+*
+* @remarks This function is a simple wrapper around `new Date()` and is provided for consistency and potential future enhancements.
+*
+* @returns The current date and time as a `Date` object.
+*/
+function getCurrentDateTime() {
+	return /* @__PURE__ */ new Date();
+}
+/**
+* * Extract Time in `HH:MM` format from given UTC value.
+*
+* @param utc UTC value in `UTC-01:30` or `UTC+01:30` format.
+* @returns The UTC value in `HH:MM` format.
+*/
+function extractTimeFromUTC(utc) {
+	return utc.replace(/^UTC[+]?/g, "");
+}
+/**
+* * Converts a UTC value in `UTC-01:30` or `UTC+01:30` format into total minutes in number.
+*
+* @param time - UTC value in `UTC-01:30` or `UTC+01:30` format.
+* @returns The total minutes elapsed since `00:00`.
+*/
+function extractMinutesFromUTC(utc) {
+	return getTotalMinutes(extractTimeFromUTC(utc));
+}
+/**
+* * Converts a number of minutes into a time string in "HH:MM" format.
+*
+* @param minutes - The number of minutes to convert. Can be a number or a numeric string.
+* @returns A string representing the time in "HH:MM" format.
+*
+* @remarks Always returns the absolute value of the minutes, ignoring the sign if they are negative.
+*
+* @example
+* convertMinutesToTime(75); // "1:15"
+* convertMinutesToTime(-45); // "0:45"
+*/
+function convertMinutesToTime(minutes) {
+	const parsed = require_utilities.normalizeNumber(minutes);
+	if (require_primitives.isUndefined(parsed)) throw new TypeError(`Invalid numeric input!`, { cause: `${minutes} cannot be converted to a number.` });
+	const numMIn = Math.abs(parsed);
+	return `${String(Math.floor(numMIn / 60))}:${String(numMIn % 60).padStart(2, "0")}`;
+}
+/**
+* * Converts a minute-based offset to a UTC offset string in the format `UTC±HH:MM`.
+*
+* @param minutes - The offset in minutes (positive or negative).
+* @returns A formatted UTC offset string like `UTC+05:30` or `UTC-04:00`.
+*/
+function formatUTCOffset(minutes) {
+	const parsed = require_utilities.normalizeNumber(minutes);
+	if (require_primitives.isUndefined(parsed)) throw new TypeError(`Invalid numeric input!`, { cause: `${minutes} cannot be converted to a number.` });
+	const sign = parsed < 0 ? "-" : "+";
+	const abs = Math.abs(parsed);
+	return `UTC${sign}${String(Math.floor(abs / 60)).padStart(2, "0")}:${String(abs % 60).padStart(2, "0")}`;
+}
+/** Get the current system's time zone identifier using {@link Intl.DateTimeFormat} API. */
+function getNativeTimeZoneId() {
+	return Intl.DateTimeFormat().resolvedOptions().timeZone;
+}
+/**
+* * Retrieves comprehensive time zone details using the {@link Intl.DateTimeFormat} API.
+* @param tzId Optional timezone identifier. Defaults to the system timezone.
+* @param date Optional date for which to resolve the information.
+* @returns Object containing time zone identifier, names, and offset.
+*/
+function getTimeZoneDetails(tzId, date) {
+	const TZ_NAME_TYPES = [
+		"long",
+		"longGeneric",
+		"longOffset"
+	];
+	const $tzId = tzId || getNativeTimeZoneId();
+	const obj = { tzIdentifier: $tzId };
+	for (const type of TZ_NAME_TYPES) {
+		const key = `tzName${type[0].toUpperCase()}${type.slice(1)}`;
+		obj[key] = require_parse._resolveNativeTzName($tzId, type, date);
+	}
+	return obj;
+}
+/** Cache for offset to time zone */
+const TZ_MAP = /* @__PURE__ */ new Map();
+/**
+* * Resolves all IANA time-zone identifiers that match a given UTC offset.
+*
+* @remarks
+* - Uses an internal in-memory cache that persists for the lifetime of the running application.
+* - The cache is lazily populated so the `offset`-to-`time-zone` mapping is computed only once per offset.
+* - Offset and time-zone identifier detection uses the {@link Intl.DateTimeFormat} API.
+*
+* @param offset The UTC offset in `"UTC±HH:MM"` format.
+* @returns An array of matching IANA time-zone identifiers, or an empty array if the offset is invalid.
+*/
+function getTimeZoneIds(offset) {
+	if (!require_guards.isValidUTCOffset(offset)) return [];
+	if (TZ_MAP.has(offset)) return TZ_MAP.get(offset) ?? [];
+	for (const zone of require_timezone.NATIVE_TZ_IDS) {
+		const off = require_parse._gmtToUtcOffset(require_parse._resolveNativeTzName(zone, "longOffset"));
+		if (off) TZ_MAP.set(off, [...TZ_MAP.get(off) ?? [], zone]);
+	}
+	return TZ_MAP.get(offset) ?? [];
+}
+/**
+* * Formats a date into a specified string format.
+*
+* @param options Options to control date and time formatting.
+*
+* @remarks
+* - If no date is provided, the current date and time will be used.
+* - If the provided date is invalid, the function will return `'Invalid Date!'`.
+* - The default format is `'dd, mmm DD, YYYY HH:mm:ss'` (e.g., `'Sun, Apr 06, 2025 16:11:55'`).
+* - By default, local time is used; set `useUTC` to `true` to format in UTC.
+* - The format string supports various tokens for date and time components, as well as literal text enclosed in square brackets.
+* - See {@link https://toolbox.nazmul-nhb.dev/docs/utilities/date/formatDate#format-tokens format tokens} for details on supported tokens.
+* - For more complex date/time manipulations, consider using the {@link https://toolbox.nazmul-nhb.dev/docs/classes/Chronos Chronos} class.
+*
+* @returns Date/time string in specified format.
+*/
+function formatDate(options) {
+	const { date = /* @__PURE__ */ new Date(), format = "dd, mmm DD, YYYY HH:mm:ss", useUTC = false } = options ?? {};
+	const $date = require_parse._dateArgsToDate(date);
+	if (isNaN($date.getTime())) return "Invalid Date!";
+	/** Get unit value for {@link $date} for specific unit in local or UTC time */
+	const _getUnitValue = (suffix) => {
+		return useUTC ? $date[`getUTC${suffix}`]() : $date[`get${suffix}`]();
+	};
+	return require_parse._formatDate(format, _getUnitValue("FullYear"), _getUnitValue("Month"), _getUnitValue("Day"), _getUnitValue("Date"), _getUnitValue("Hours"), _getUnitValue("Minutes"), _getUnitValue("Seconds"), _getUnitValue("Milliseconds"), useUTC ? "Z" : formatUTCOffset(-$date.getTimezoneOffset()).slice(3));
+}
+/**
+* * Formats a time-only string into a formatted time string.
+*
+* @param time - Time string to be formatted. Supported formats include:
+* - `HH:mm` → e.g., `'14:50'`
+* - `HH:mm:ss` → e.g., `'14:50:00'`
+* - `HH:mm:ss.mss` → e.g., `'14:50:00.800'`
+* - `HH:mm+TimeZoneOffset(HH)` → e.g., `'14:50+06'`
+* - `HH:mm+TimeZoneOffset(HH:mm)` → e.g., `'14:50+06:00'`
+* - `HH:mm:ss+TimeZoneOffset(HH)` → e.g., `'14:50:00+06'`
+* - `HH:mm:ss+TimeZoneOffset(HH:mm)` → e.g., `'14:50:00+05:30'`
+* - `HH:mm:ss.mss+TimeZoneOffset(HH)` → e.g., `'14:50:00.800+06'`
+* - `HH:mm:ss.mss+TimeZoneOffset(HH:mm)` → e.g., `'14:50:00.800+06:30'`
+*
+* - *Input will default to today's date and assume local timezone if no offset is provided.*
+*
+* @param format - Format tokens accepted by {@link formatDate} method ({@link TimeOnlyFormat}) for time part only.
+*                 Default: `hh:mm:ss a` → 02:33:36 pm.
+* @returns Formatted time string in local (System) time.
+*/
+function formatTimePart(time, format) {
+	return formatDate({
+		date: `${formatDate({ format: "YYYY-MM-DD" })}T${require_parse._normalizeOffset(time)}`,
+		format: format || "hh:mm:ss a"
+	});
+}
+/**
+* * Formats a date as a relative time string (e.g., "5m ago", "2h from now").
+*
+* @param date - The date to format, which can be a `Date` object, a date string, or a timestamp number.
+* @param format - Optional format string for dates older than 7 days. Defaults to `'mmm D, yyyy hh:mm a'`.
+* @returns A relative time string if the date is within the last 7 days, otherwise a formatted date string.
+*
+* @remarks
+* - If date is provided but `undefined`, current date and time will be used.
+* - If the provided date is invalid, the function will return `'Invalid Date!'`.
+* - For dates within the last 7 days, the output will be in the format of "Xm ago" or "Xh from now".
+* - For dates older than 7 days, the output will be formatted using the provided `format` string or the default format if none is provided.
+*
+* @example
+* formatDateRelative(Date.now() - 5 * 60000); // "5m ago"
+* formatDateRelative(Date.now() + 2 * 3600000); // "2h from now"
+* formatDateRelative(Date.now() - 10 * 86400000); // "Apr 6, 2026 04:11 PM" (formatted date string)
+*/
+function formatDateRelative(date, format) {
+	const $date = require_parse._dateArgsToDate(date);
+	if (isNaN($date.getTime())) return "Invalid Date!";
+	const now = Date.now();
+	const then = $date.getTime();
+	const diff = Math.abs(now - then);
+	const minutes = Math.floor(diff / 6e4);
+	const hours = Math.floor(diff / 36e5);
+	const days = Math.floor(diff / 864e5);
+	const suffix = then < now ? "ago" : "from now";
+	if (minutes < 1) return "Just now";
+	if (minutes < 60) return `${minutes}m ${suffix}`;
+	if (hours < 24) return `${hours}h ${suffix}`;
+	if (days < 7) return `${days}d ${suffix}`;
+	return formatDate({
+		date,
+		format: format || "mmm D, yyyy hh:mm a"
+	});
+}
+/** Get timestamp in ISO 8601 format. */
+function getTimestamp(args, format) {
+	let $value;
+	let $format;
+	const _isTsOptions = (opt) => {
+		return require_specials.isObject(opt) && ("value" in opt || "format" in opt);
+	};
+	if (_isTsOptions(args)) {
+		$value = args.value || /* @__PURE__ */ new Date();
+		$format = args.format || "utc";
+	} else {
+		$value = args || /* @__PURE__ */ new Date();
+		$format = format || "utc";
+	}
+	let date = require_parse._dateArgsToDate($value);
+	if (isNaN(date.getTime())) date = /* @__PURE__ */ new Date();
+	if ($format === "local") {
+		const offsetMins = date.getTimezoneOffset();
+		const localDate = /* @__PURE__ */ new Date(date.getTime() - offsetMins * 6e4);
+		const offset = formatUTCOffset(-offsetMins).slice(3);
+		return localDate.toISOString().replace("Z", offset);
+	}
+	return date.toISOString();
+}
+
+//#endregion
+//#region src/date/greet.ts
+/**
+* * Returns a greeting message based on the provided time or current time.
+*
+* @param configs - Configuration options for greeting times and messages.
+* @returns The appropriate greeting message.
+*/
+function getGreeting(configs) {
+	const { morningEnds = "11:59", noonEnds = "12:59", afternoonEnds = "17:59", eveningEnds = "23:59", midnightEnds = "02:59", currentTime, appendToMsg = "", prependToMsg = "", morningMessage = "Good Morning!", noonMessage = "Good Noon!", afternoonMessage = "Good Afternoon!", eveningMessage = "Good Evening!", midnightMessage = "Hello, Night Owl!", defaultMessage = "Greetings!" } = configs || {};
+	let hour;
+	let minute;
+	if (currentTime && require_guards.isValidTime(currentTime)) [hour, minute] = extractHourMinute(currentTime);
+	else {
+		hour = getCurrentDateTime().getHours();
+		minute = getCurrentDateTime().getMinutes();
+	}
+	const currentTotalMinutes = hour * 60 + minute;
+	const morningEndMinutes = getTotalMinutes(morningEnds);
+	const noonEndMinutes = getTotalMinutes(noonEnds);
+	const afternoonEndMinutes = getTotalMinutes(afternoonEnds);
+	const eveningEndMinutes = getTotalMinutes(eveningEnds);
+	if (currentTotalMinutes <= getTotalMinutes(midnightEnds)) return prependToMsg.concat(midnightMessage.concat(appendToMsg));
+	else if (currentTotalMinutes <= morningEndMinutes) return prependToMsg.concat(morningMessage.concat(appendToMsg));
+	else if (currentTotalMinutes <= noonEndMinutes) return prependToMsg.concat(noonMessage.concat(appendToMsg));
+	else if (currentTotalMinutes <= afternoonEndMinutes) return prependToMsg.concat(afternoonMessage.concat(appendToMsg));
+	else if (currentTotalMinutes <= eveningEndMinutes) return prependToMsg.concat(eveningMessage.concat(appendToMsg));
+	else return prependToMsg.concat(defaultMessage.concat(appendToMsg));
+}
+
+//#endregion
+exports.convertMinutesToHourMinutes = convertMinutesToTime;
+exports.convertMinutesToTime = convertMinutesToTime;
+exports.convertMinutesToUTCOffset = formatUTCOffset;
+exports.extractHourMinute = extractHourMinute;
+exports.extractMinutesFromUTC = extractMinutesFromUTC;
+exports.extractTimeFromUTC = extractTimeFromUTC;
+exports.extractTimeStringFromUTC = extractTimeFromUTC;
+exports.extractTotalMinutesFromTime = getTotalMinutes;
+exports.formatDate = formatDate;
+exports.formatDateRelative = formatDateRelative;
+exports.formatDateTime = formatDate;
+exports.formatRelativeDate = formatDateRelative;
+exports.formatRelativeTime = formatDateRelative;
+exports.formatTimePart = formatTimePart;
+exports.formatUTCOffset = formatUTCOffset;
+exports.generateGreeting = getGreeting;
+exports.getCurrentDateTime = getCurrentDateTime;
+exports.getCurrentTime = getCurrentDateTime;
+exports.getGreeting = getGreeting;
+exports.getHourMinutesFromMinutes = convertMinutesToTime;
+exports.getMinutesFromUTC = extractMinutesFromUTC;
+exports.getNativeTimeZoneId = getNativeTimeZoneId;
+exports.getTimeFromMinutes = convertMinutesToTime;
+exports.getTimeStringFromUTC = extractTimeFromUTC;
+exports.getTimeZoneDetails = getTimeZoneDetails;
+exports.getTimeZoneIds = getTimeZoneIds;
+exports.getTimestamp = getTimestamp;
+exports.getTotalMinutes = getTotalMinutes;
+exports.getTotalMinutesFromTime = getTotalMinutes;
+exports.getTotalMinutesFromUTC = extractMinutesFromUTC;
+exports.greet = getGreeting;
+exports.minutesToUTCOffset = formatUTCOffset;
+exports.parseMSec = require_parse.parseMSec;
+exports.parseMs = require_parse.parseMSec;