nhb-toolbox 4.28.57 → 4.28.64

package/CHANGELOG.md

@@ -4,6 +4,16 @@
 
 All notable changes to the package will be documented here.
 
+## [4.28.64] - 2026-01-15
+
+- **Added** new `zodiacPlugin` method: `getZodiacMeta` to retrieve zodiac *metadata* for a given *zodiac sign*.
+
+## [4.28.60] - 2026-01-13
+
+- **Fixed** `Chronos.getZodiacSign` boundary handling to correctly wrap across year transitions for *zodiac presets*.
+- **Improved** zodiac resolution logic to ensure consistent results for early-January dates without altering existing zodiac presets.
+- **Updated** `ZodiacArray` and `ZodiacOptions` types to support custom zodiac definitions with *correctly inferred sign names*.
+
 ## [4.28.57] - 2026-01-07
 
 - **Enhanced** `Color.isLightColor` with an *optional brightness threshold* for custom light/dark detection.

package/dist/cjs/date/constants.js

@@ -74,22 +74,20 @@ exports.WESTERN_ZODIAC_SIGNS = /* @__PURE__ */ Object.freeze([
     ['Libra', [9, 23]],
     ['Scorpio', [10, 23]],
     ['Sagittarius', [11, 22]],
-    ['Capricorn', [12, 22]],
 ]);
 exports.VEDIC_ZODIAC_SIGNS = /* @__PURE__ */ Object.freeze([
     ['Capricorn', [1, 14]],
     ['Aquarius', [2, 13]],
     ['Pisces', [3, 14]],
-    ['Aries', [4, 13]],
-    ['Taurus', [5, 14]],
-    ['Gemini', [6, 14]],
+    ['Aries', [4, 14]],
+    ['Taurus', [5, 15]],
+    ['Gemini', [6, 15]],
     ['Cancer', [7, 16]],
-    ['Leo', [8, 16]],
-    ['Virgo', [9, 16]],
-    ['Libra', [10, 16]],
-    ['Scorpio', [11, 15]],
-    ['Sagittarius', [12, 15]],
-    ['Capricorn', [1, 14]],
+    ['Leo', [8, 17]],
+    ['Virgo', [9, 17]],
+    ['Libra', [10, 17]],
+    ['Scorpio', [11, 16]],
+    ['Sagittarius', [12, 16]],
 ]);
 exports.ZODIAC_PRESETS = /* @__PURE__ */ Object.freeze({
     western: exports.WESTERN_ZODIAC_SIGNS,

package/dist/cjs/date/plugins/zodiacPlugin.js

@@ -2,9 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.zodiacPlugin = void 0;
 const constants_1 = require("../constants");
+const helpers_1 = require("../helpers");
 const zodiacPlugin = ($Chronos) => {
+    function _toHundreds(range) {
+        return range[0] * 100 + range[1];
+    }
+    function _resolveSigns(options) {
+        const { preset = 'western', custom } = options ?? {};
+        const sorted = [...(custom ?? constants_1.ZODIAC_PRESETS[preset])].sort((a, b) => _toHundreds(a[1]) - _toHundreds(b[1]));
+        return sorted;
+    }
     $Chronos.prototype.getZodiacSign = function (options) {
-        const { birthDate, preset = 'western', custom } = options ?? {};
+        const { birthDate } = options ?? {};
         let month;
         let date;
         if (birthDate && birthDate?.includes('-')) {
@@ -14,17 +23,35 @@ const zodiacPlugin = ($Chronos) => {
             month = this.isoMonth;
             date = this.date;
         }
-        const signs = [...(custom ?? constants_1.ZODIAC_PRESETS[preset])].sort((a, b) => a[1][0] * 100 + a[1][1] - (b[1][0] * 100 + b[1][1]));
-        for (let i = signs.length - 1; i >= 0; i--) {
-            const [sign, [m, d]] = signs[i];
+        const sortedSigns = _resolveSigns(options);
+        for (let i = sortedSigns.length - 1; i >= 0; i--) {
+            const [sign, [m, d]] = sortedSigns[i];
             if (month > m || (month === m && date >= d)) {
                 return sign;
             }
+            if (i === 0) {
+                return sortedSigns.at(-1)[0];
+            }
         }
-        return signs[0][0];
+        return sortedSigns[0][0];
     };
     $Chronos.prototype.zodiac = function (options) {
         return this.getZodiacSign(options);
     };
+    $Chronos.prototype.getZodiacMeta = function (sign, options) {
+        const sortedSigns = _resolveSigns(options);
+        const index = sortedSigns.findIndex(([s]) => s === sign);
+        if (index === -1) {
+            throw new RangeError(`Invalid zodiac sign: "${sign}"`);
+        }
+        const [startMonth, startDate] = sortedSigns[index][1];
+        const [endMonth, endDate] = (sortedSigns[index + 1] ?? sortedSigns[0])[1];
+        return {
+            index,
+            sign,
+            start: `${(0, helpers_1._padZero)(startMonth)}-${(0, helpers_1._padZero)(startDate)}`,
+            end: `${(0, helpers_1._padZero)(endMonth)}-${(0, helpers_1._padZero)(endDate - 1)}`,
+        };
+    };
 };
 exports.zodiacPlugin = zodiacPlugin;

package/dist/dts/date/constants.d.ts

@@ -21,15 +21,15 @@ export declare const SORTED_TIME_FORMATS: readonly ("MM" | "SS" | "ms" | "DD" |
 /** Ranges for day parts. */
 export declare const DATE_PART_RANGES: Readonly<Record<DayPart, [ClockHour, ClockHour]>>;
 /** Western Zodiac Signs */
-export declare const WESTERN_ZODIAC_SIGNS: readonly [readonly ["Capricorn", readonly [12, 22]], readonly ["Aquarius", readonly [1, 20]], readonly ["Pisces", readonly [2, 19]], readonly ["Aries", readonly [3, 21]], readonly ["Taurus", readonly [4, 20]], readonly ["Gemini", readonly [5, 21]], readonly ["Cancer", readonly [6, 21]], readonly ["Leo", readonly [7, 23]], readonly ["Virgo", readonly [8, 23]], readonly ["Libra", readonly [9, 23]], readonly ["Scorpio", readonly [10, 23]], readonly ["Sagittarius", readonly [11, 22]], readonly ["Capricorn", readonly [12, 22]]];
+export declare const WESTERN_ZODIAC_SIGNS: readonly [readonly ["Capricorn", readonly [12, 22]], readonly ["Aquarius", readonly [1, 20]], readonly ["Pisces", readonly [2, 19]], readonly ["Aries", readonly [3, 21]], readonly ["Taurus", readonly [4, 20]], readonly ["Gemini", readonly [5, 21]], readonly ["Cancer", readonly [6, 21]], readonly ["Leo", readonly [7, 23]], readonly ["Virgo", readonly [8, 23]], readonly ["Libra", readonly [9, 23]], readonly ["Scorpio", readonly [10, 23]], readonly ["Sagittarius", readonly [11, 22]]];
 /** Vedic Zodiac Sign */
-export declare const VEDIC_ZODIAC_SIGNS: readonly [readonly ["Capricorn", readonly [1, 14]], readonly ["Aquarius", readonly [2, 13]], readonly ["Pisces", readonly [3, 14]], readonly ["Aries", readonly [4, 13]], readonly ["Taurus", readonly [5, 14]], readonly ["Gemini", readonly [6, 14]], readonly ["Cancer", readonly [7, 16]], readonly ["Leo", readonly [8, 16]], readonly ["Virgo", readonly [9, 16]], readonly ["Libra", readonly [10, 16]], readonly ["Scorpio", readonly [11, 15]], readonly ["Sagittarius", readonly [12, 15]], readonly ["Capricorn", readonly [1, 14]]];
+export declare const VEDIC_ZODIAC_SIGNS: readonly [readonly ["Capricorn", readonly [1, 14]], readonly ["Aquarius", readonly [2, 13]], readonly ["Pisces", readonly [3, 14]], readonly ["Aries", readonly [4, 14]], readonly ["Taurus", readonly [5, 15]], readonly ["Gemini", readonly [6, 15]], readonly ["Cancer", readonly [7, 16]], readonly ["Leo", readonly [8, 17]], readonly ["Virgo", readonly [9, 17]], readonly ["Libra", readonly [10, 17]], readonly ["Scorpio", readonly [11, 16]], readonly ["Sagittarius", readonly [12, 16]]];
 /** Zodiac Signs Presets */
 export declare const ZODIAC_PRESETS: Readonly<{
-    readonly western: readonly [readonly ["Capricorn", readonly [12, 22]], readonly ["Aquarius", readonly [1, 20]], readonly ["Pisces", readonly [2, 19]], readonly ["Aries", readonly [3, 21]], readonly ["Taurus", readonly [4, 20]], readonly ["Gemini", readonly [5, 21]], readonly ["Cancer", readonly [6, 21]], readonly ["Leo", readonly [7, 23]], readonly ["Virgo", readonly [8, 23]], readonly ["Libra", readonly [9, 23]], readonly ["Scorpio", readonly [10, 23]], readonly ["Sagittarius", readonly [11, 22]], readonly ["Capricorn", readonly [12, 22]]];
-    readonly vedic: readonly [readonly ["Capricorn", readonly [1, 14]], readonly ["Aquarius", readonly [2, 13]], readonly ["Pisces", readonly [3, 14]], readonly ["Aries", readonly [4, 13]], readonly ["Taurus", readonly [5, 14]], readonly ["Gemini", readonly [6, 14]], readonly ["Cancer", readonly [7, 16]], readonly ["Leo", readonly [8, 16]], readonly ["Virgo", readonly [9, 16]], readonly ["Libra", readonly [10, 16]], readonly ["Scorpio", readonly [11, 15]], readonly ["Sagittarius", readonly [12, 15]], readonly ["Capricorn", readonly [1, 14]]];
-    readonly tropical: readonly [readonly ["Capricorn", readonly [12, 22]], readonly ["Aquarius", readonly [1, 20]], readonly ["Pisces", readonly [2, 19]], readonly ["Aries", readonly [3, 21]], readonly ["Taurus", readonly [4, 20]], readonly ["Gemini", readonly [5, 21]], readonly ["Cancer", readonly [6, 21]], readonly ["Leo", readonly [7, 23]], readonly ["Virgo", readonly [8, 23]], readonly ["Libra", readonly [9, 23]], readonly ["Scorpio", readonly [10, 23]], readonly ["Sagittarius", readonly [11, 22]], readonly ["Capricorn", readonly [12, 22]]];
-    readonly sidereal: readonly [readonly ["Capricorn", readonly [1, 14]], readonly ["Aquarius", readonly [2, 13]], readonly ["Pisces", readonly [3, 14]], readonly ["Aries", readonly [4, 13]], readonly ["Taurus", readonly [5, 14]], readonly ["Gemini", readonly [6, 14]], readonly ["Cancer", readonly [7, 16]], readonly ["Leo", readonly [8, 16]], readonly ["Virgo", readonly [9, 16]], readonly ["Libra", readonly [10, 16]], readonly ["Scorpio", readonly [11, 15]], readonly ["Sagittarius", readonly [12, 15]], readonly ["Capricorn", readonly [1, 14]]];
+    readonly western: readonly [readonly ["Capricorn", readonly [12, 22]], readonly ["Aquarius", readonly [1, 20]], readonly ["Pisces", readonly [2, 19]], readonly ["Aries", readonly [3, 21]], readonly ["Taurus", readonly [4, 20]], readonly ["Gemini", readonly [5, 21]], readonly ["Cancer", readonly [6, 21]], readonly ["Leo", readonly [7, 23]], readonly ["Virgo", readonly [8, 23]], readonly ["Libra", readonly [9, 23]], readonly ["Scorpio", readonly [10, 23]], readonly ["Sagittarius", readonly [11, 22]]];
+    readonly vedic: readonly [readonly ["Capricorn", readonly [1, 14]], readonly ["Aquarius", readonly [2, 13]], readonly ["Pisces", readonly [3, 14]], readonly ["Aries", readonly [4, 14]], readonly ["Taurus", readonly [5, 15]], readonly ["Gemini", readonly [6, 15]], readonly ["Cancer", readonly [7, 16]], readonly ["Leo", readonly [8, 17]], readonly ["Virgo", readonly [9, 17]], readonly ["Libra", readonly [10, 17]], readonly ["Scorpio", readonly [11, 16]], readonly ["Sagittarius", readonly [12, 16]]];
+    readonly tropical: readonly [readonly ["Capricorn", readonly [12, 22]], readonly ["Aquarius", readonly [1, 20]], readonly ["Pisces", readonly [2, 19]], readonly ["Aries", readonly [3, 21]], readonly ["Taurus", readonly [4, 20]], readonly ["Gemini", readonly [5, 21]], readonly ["Cancer", readonly [6, 21]], readonly ["Leo", readonly [7, 23]], readonly ["Virgo", readonly [8, 23]], readonly ["Libra", readonly [9, 23]], readonly ["Scorpio", readonly [10, 23]], readonly ["Sagittarius", readonly [11, 22]]];
+    readonly sidereal: readonly [readonly ["Capricorn", readonly [1, 14]], readonly ["Aquarius", readonly [2, 13]], readonly ["Pisces", readonly [3, 14]], readonly ["Aries", readonly [4, 14]], readonly ["Taurus", readonly [5, 15]], readonly ["Gemini", readonly [6, 15]], readonly ["Cancer", readonly [7, 16]], readonly ["Leo", readonly [8, 17]], readonly ["Virgo", readonly [9, 17]], readonly ["Libra", readonly [10, 17]], readonly ["Scorpio", readonly [11, 16]], readonly ["Sagittarius", readonly [12, 16]]];
 }>;
 /** Variants of different time units */
 export declare const TIME_UNIT_VARIANTS: Readonly<{

package/dist/dts/date/plugins/zodiacPlugin.d.ts

@@ -1,4 +1,4 @@
-import type { $Chronos, ZodiacOptions, ZodiacSign } from '../types';
+import type { $Chronos, ZodiacMeta, ZodiacMetaOptions, ZodiacOptions, ZodiacSign } from '../types';
 declare module '../Chronos' {
     interface Chronos {
         /**
@@ -6,7 +6,7 @@ declare module '../Chronos' {
          * @param options Optional config to choose preset or provide custom zodiac date ranges.
          * @returns The matching zodiac sign from preset/custom list.
          */
-        getZodiacSign(options?: ZodiacOptions): ZodiacSign;
+        getZodiacSign<Sign extends string = ZodiacSign>(options?: ZodiacOptions<Sign>): Sign;
         /**
          * @instance Returns the zodiac sign based on current date or `birthDate` option.
          * @remarks This method is an alias for {@link https://toolbox.nazmul-nhb.dev/docs/classes/Chronos/names#getzodiacsign getZodiacSign} method.
@@ -14,8 +14,24 @@ declare module '../Chronos' {
          * @param options Optional config to choose preset or provide custom zodiac date ranges.
          * @returns The matching zodiac sign from preset/custom list.
          */
-        zodiac(options?: ZodiacOptions): ZodiacSign;
+        zodiac<Sign extends string = ZodiacSign>(options?: ZodiacOptions<Sign>): Sign;
+        /**
+         * @instance Returns detailed metadata for a given zodiac sign based on the selected `preset` or custom ranges.
+         *
+         * @remarks
+         * - The metadata includes the sign's `index` within the normalized zodiac order, its inclusive start and end dates.
+         *   - **Note:** The returned `index` represents the chronological position of the zodiac sign based on Gregorian month–day ordering and may vary between different zodiac variants.
+         * - Handles year-boundary wrapping correctly (e.g. Capricorn, Sagittarius).
+         *
+         * @param sign The zodiac sign to retrieve metadata for.
+         * @param options Optional configuration to select a zodiac preset or provide custom ranges.
+         *
+         * @throws A {@link RangeError} if the provided sign does not exist in the resolved zodiac set.
+         *
+         * @returns A metadata object describing the zodiac sign's position and date range.
+         */
+        getZodiacMeta<Sign extends string = ZodiacSign>(sign: Sign, options?: ZodiacMetaOptions<Sign>): ZodiacMeta<Sign>;
     }
 }
-/** * Plugin to inject `getZodiacSign`/`zodiac` method */
+/** * Plugin to inject `zodiac` related methods */
 export declare const zodiacPlugin: ($Chronos: $Chronos) => void;

package/dist/dts/date/types.d.ts

@@ -304,20 +304,43 @@ export type DayPartConfig = Record<DayPart, [ClockHour, ClockHour]>;
 export type Quarter = 1 | 2 | 3 | 4;
 /** Academic year, e.g. `2024-2025` */
 export type AcademicYear = `${number}-${number}`;
-/** Names of Zodiac signs */
+/** Names of standard Zodiac signs */
 export type ZodiacSign = (typeof WESTERN_ZODIAC_SIGNS)[number][0];
 /** Presets for Zodiac Sign Configuration */
 export type ZodiacPreset = keyof typeof ZODIAC_PRESETS;
 /** Shape of Zodiac signs array */
-export type ZodiacArray = Array<[ZodiacSign, [NumberRange<1, 12>, NumberRange<1, 31>]]>;
+export type ZodiacArray<Sign extends string = ZodiacSign> = Array<[Sign, [NumberRange<1, 12>, NumberRange<1, 31>]] | Readonly<[Sign, Readonly<[NumberRange<1, 12>, NumberRange<1, 31>]>]>>;
+/** Zodiac metadata options */
+export interface ZodiacMetaOptions<Sign extends string = ZodiacSign> {
+    /**
+     * Optional Zodiac preset to use. Default is `western`.
+     * - **Note:** `western` and `tropical`, `vedic` and `sidereal` are same.
+     */
+    preset?: ZodiacPreset;
+    /** Custom Zodiac date ranges, overrides {@link preset presets}. */
+    custom?: ZodiacArray<Sign> | Readonly<ZodiacArray<Sign>>;
+}
 /** Options for configuring Zodiac sign getter */
-export interface ZodiacOptions {
-    /** - Optional birthdate in `MM-DD` format (1-based month). */
+export interface ZodiacOptions<Sign extends string = ZodiacSign> extends ZodiacMetaOptions<Sign> {
+    /** - Optional birthdate in `MM-DD` format (`1`-based month). */
     birthDate?: MonthDateString;
-    /** Optional Zodiac preset to use. Default is `western`. `western` and `tropical`, `vedic` and `sidereal` are same. */
-    preset?: ZodiacPreset;
-    /** Custom Zodiac date ranges. */
-    custom?: ZodiacArray;
+}
+/** Represents resolved metadata for a zodiac sign */
+export interface ZodiacMeta<Sign extends string = ZodiacSign> {
+    /**
+     * Index (`0`-based) of the zodiac sign within the resolved and chronologically sorted zodiac list.
+     *
+     * ⚠️ **Notes:**
+     * - The `index` is determined by the Gregorian month–day order of zodiac start dates and may differ between variants (e.g. Western vs Vedic).
+     * - This `index` should not be interpreted as a traditional or mythological zodiac ordering.
+     */
+    index: number;
+    /** The zodiac sign name. */
+    sign: Sign;
+    /** Inclusive start date of the zodiac sign in `MM-DD` format. */
+    start: MonthDateString;
+    /** Inclusive end date of the zodiac sign in `MM-DD` format. */
+    end: MonthDateString;
 }
 /** - Represents the full name of a weekday, e.g., 'Monday', 'Tuesday' etc. */
 export type WeekDay = (typeof DAYS)[number];

package/dist/esm/date/constants.js

@@ -71,22 +71,20 @@ export const WESTERN_ZODIAC_SIGNS = /* @__PURE__ */ Object.freeze([
     ['Libra', [9, 23]],
     ['Scorpio', [10, 23]],
     ['Sagittarius', [11, 22]],
-    ['Capricorn', [12, 22]],
 ]);
 export const VEDIC_ZODIAC_SIGNS = /* @__PURE__ */ Object.freeze([
     ['Capricorn', [1, 14]],
     ['Aquarius', [2, 13]],
     ['Pisces', [3, 14]],
-    ['Aries', [4, 13]],
-    ['Taurus', [5, 14]],
-    ['Gemini', [6, 14]],
+    ['Aries', [4, 14]],
+    ['Taurus', [5, 15]],
+    ['Gemini', [6, 15]],
     ['Cancer', [7, 16]],
-    ['Leo', [8, 16]],
-    ['Virgo', [9, 16]],
-    ['Libra', [10, 16]],
-    ['Scorpio', [11, 15]],
-    ['Sagittarius', [12, 15]],
-    ['Capricorn', [1, 14]],
+    ['Leo', [8, 17]],
+    ['Virgo', [9, 17]],
+    ['Libra', [10, 17]],
+    ['Scorpio', [11, 16]],
+    ['Sagittarius', [12, 16]],
 ]);
 export const ZODIAC_PRESETS = /* @__PURE__ */ Object.freeze({
     western: WESTERN_ZODIAC_SIGNS,

package/dist/esm/date/plugins/zodiacPlugin.js

@@ -1,7 +1,16 @@
 import { ZODIAC_PRESETS } from '../constants.js';
+import { _padZero } from '../helpers.js';
 export const zodiacPlugin = ($Chronos) => {
+    function _toHundreds(range) {
+        return range[0] * 100 + range[1];
+    }
+    function _resolveSigns(options) {
+        const { preset = 'western', custom } = options ?? {};
+        const sorted = [...(custom ?? ZODIAC_PRESETS[preset])].sort((a, b) => _toHundreds(a[1]) - _toHundreds(b[1]));
+        return sorted;
+    }
     $Chronos.prototype.getZodiacSign = function (options) {
-        const { birthDate, preset = 'western', custom } = options ?? {};
+        const { birthDate } = options ?? {};
         let month;
         let date;
         if (birthDate && birthDate?.includes('-')) {
@@ -11,16 +20,34 @@ export const zodiacPlugin = ($Chronos) => {
             month = this.isoMonth;
             date = this.date;
         }
-        const signs = [...(custom ?? ZODIAC_PRESETS[preset])].sort((a, b) => a[1][0] * 100 + a[1][1] - (b[1][0] * 100 + b[1][1]));
-        for (let i = signs.length - 1; i >= 0; i--) {
-            const [sign, [m, d]] = signs[i];
+        const sortedSigns = _resolveSigns(options);
+        for (let i = sortedSigns.length - 1; i >= 0; i--) {
+            const [sign, [m, d]] = sortedSigns[i];
             if (month > m || (month === m && date >= d)) {
                 return sign;
             }
+            if (i === 0) {
+                return sortedSigns.at(-1)[0];
+            }
         }
-        return signs[0][0];
+        return sortedSigns[0][0];
     };
     $Chronos.prototype.zodiac = function (options) {
         return this.getZodiacSign(options);
     };
+    $Chronos.prototype.getZodiacMeta = function (sign, options) {
+        const sortedSigns = _resolveSigns(options);
+        const index = sortedSigns.findIndex(([s]) => s === sign);
+        if (index === -1) {
+            throw new RangeError(`Invalid zodiac sign: "${sign}"`);
+        }
+        const [startMonth, startDate] = sortedSigns[index][1];
+        const [endMonth, endDate] = (sortedSigns[index + 1] ?? sortedSigns[0])[1];
+        return {
+            index,
+            sign,
+            start: `${_padZero(startMonth)}-${_padZero(startDate)}`,
+            end: `${_padZero(endMonth)}-${_padZero(endDate - 1)}`,
+        };
+    };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nhb-toolbox",
-  "version": "4.28.57",
+  "version": "4.28.64",
   "description": "A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -46,9 +46,9 @@
   "devDependencies": {
     "@eslint/js": "^9.39.2",
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.0.3",
-    "@typescript-eslint/eslint-plugin": "^8.51.0",
-    "@typescript-eslint/parser": "^8.51.0",
+    "@types/node": "^25.0.6",
+    "@typescript-eslint/eslint-plugin": "^8.53.0",
+    "@typescript-eslint/parser": "^8.53.0",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
@@ -60,7 +60,7 @@
     "prettier": "^3.7.4",
     "ts-jest": "^29.4.6",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.51.0"
+    "typescript-eslint": "^8.53.0"
   },
   "keywords": [
     "toolbox",