nhb-toolbox 4.28.60 → 4.28.64

package/CHANGELOG.md

@@ -4,6 +4,10 @@
 
 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*.

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,23 +23,35 @@ const zodiacPlugin = ($Chronos) => {
             month = this.isoMonth;
             date = this.date;
         }
-        const _toHundreds = (range) => {
-            return range[0] * 100 + range[1];
-        };
-        const signs = [...(custom ?? constants_1.ZODIAC_PRESETS[preset])].sort((a, b) => _toHundreds(a[1]) - _toHundreds(b[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 signs.at(-1)[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/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 {
         /**
@@ -15,6 +15,22 @@ declare module '../Chronos' {
          * @returns The matching zodiac sign from preset/custom list.
          */
         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 `zodiac` related methods */

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

@@ -310,15 +310,38 @@ export type ZodiacSign = (typeof WESTERN_ZODIAC_SIGNS)[number][0];
 export type ZodiacPreset = keyof typeof ZODIAC_PRESETS;
 /** Shape of Zodiac signs array */
 export type ZodiacArray<Sign extends string = ZodiacSign> = Array<[Sign, [NumberRange<1, 12>, NumberRange<1, 31>]] | Readonly<[Sign, Readonly<[NumberRange<1, 12>, NumberRange<1, 31>]>]>>;
-/** Options for configuring Zodiac sign getter */
-export interface ZodiacOptions<Sign extends string = ZodiacSign> {
-    /** - 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. */
+/** 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 presets. */
+    /** Custom Zodiac date ranges, overrides {@link preset presets}. */
     custom?: ZodiacArray<Sign> | Readonly<ZodiacArray<Sign>>;
 }
+/** Options for configuring Zodiac sign getter */
+export interface ZodiacOptions<Sign extends string = ZodiacSign> extends ZodiacMetaOptions<Sign> {
+    /** - Optional birthdate in `MM-DD` format (`1`-based month). */
+    birthDate?: MonthDateString;
+}
+/** 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];
 /** - Represents the full name of a month, e.g., 'January', 'February' etc. */

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,22 +20,34 @@ export const zodiacPlugin = ($Chronos) => {
             month = this.isoMonth;
             date = this.date;
         }
-        const _toHundreds = (range) => {
-            return range[0] * 100 + range[1];
-        };
-        const signs = [...(custom ?? ZODIAC_PRESETS[preset])].sort((a, b) => _toHundreds(a[1]) - _toHundreds(b[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 signs.at(-1)[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.60",
+  "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",