chronolite-time 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adithya Gowda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,211 @@
+# chronolite-time ⏱️ — Natural Language Time Parser
+
+[![npm version](https://img.shields.io/npm/v/chronolite-time.svg)](https://www.npmjs.com/package/chronolite-time)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+chronolite-time is a lightweight JavaScript library that converts **human-readable time expressions** into machine-friendly objects and timestamps.
+
+It supports:
+
+- ⏳ **Durations** (`3 hours`, `1.5 days`)
+- 🗓 **Relative dates** (`tomorrow`, `in 2 hours`, `next monday`)
+- 📅 **Absolute dates** (`2026-03-15`, `Feb 20 2026`, `15/03/2026`)
+
+Built for schedulers, reminders, bots, dashboards, and automation systems.
+
+---
+
+## ✨ Features
+
+- **Natural language duration parsing**
+- **Relative time calculation** based on current system time
+- **Absolute calendar date parsing**
+- **Strict validation** (blocks invalid dates like `31/02/2026`)
+- **Supports mixed units** (`1 hour and 30 minutes`)
+- **Handles time fragments** (`at 5pm`, `10:30am`)
+- **Returns Unix timestamps and ISO strings**
+- **Zero dependencies**
+- **ES Modules support**
+
+---
+
+## 🚀 Installation
+
+```bash
+npm install chronolite-time
+```
+
+---
+
+## 📖 Usage
+
+### Basic Example
+
+```javascript
+import { parseTime } from "chronolite-time";
+
+// Duration parsing
+const duration = parseTime("3 hours");
+console.log(duration);
+
+// Relative time parsing
+const relative = parseTime("tomorrow at 5pm");
+console.log(relative);
+
+// Absolute date parsing
+const absolute = parseTime("2026-03-15");
+console.log(absolute);
+```
+
+### CommonJS
+
+If using CommonJS:
+
+```javascript
+const { parseTime } = await import("chronolite-time");
+```
+
+---
+
+## 📦 Return Format
+
+chronolite-time returns different objects depending on the input type:
+
+### Duration
+```javascript
+{
+  type: "duration",
+  milliseconds: number
+}
+```
+
+### Relative / Absolute
+```javascript
+{
+  type: "relative" | "absolute",
+  unix: number,
+  iso: string
+}
+```
+
+### Ranges
+Ranges like `this week` or `next month` return:
+```javascript
+{
+  type: "relative-range",
+  start: string,
+  end: string
+}
+```
+
+---
+
+## 🧪 Examples
+
+### Duration
+```javascript
+parseTime("1 hour and 30 minutes");
+```
+**Output:**
+```json
+{
+  "type": "duration",
+  "milliseconds": 5400000
+}
+```
+
+### Relative
+```javascript
+parseTime("in 2 hours");
+```
+**Output (example):**
+```json
+{
+  "type": "relative",
+  "unix": 1707678000000,
+  "iso": "2026-02-11T19:00:00.000Z"
+}
+```
+
+### Absolute
+```javascript
+parseTime("Feb 20 2026");
+```
+**Output:**
+```json
+{
+  "type": "absolute",
+  "unix": 1771545600000,
+  "iso": "2026-02-20T00:00:00.000Z"
+}
+```
+
+---
+
+## 🧠 Supported Formats
+
+### Durations
+- `3h`, `3 hours`
+- `2 hours`
+- `1.5 days`
+- `1 hour and 30 minutes`
+
+### Relative
+- `today`, `tomorrow`, `yesterday`
+- `in 3 hours`
+- `next monday`
+- `this week`
+- `next month`
+- `tomorrow at 5pm`
+
+### Absolute
+- `2026-03-15`
+- `15/03/2026`
+- `Feb 20 2026`
+
+> [!NOTE]
+> Invalid dates are strictly rejected (e.g., `31/02/2026` or `2026-02-31`).
+
+---
+
+## 🛠 Typical Use Cases
+
+- **Reminder apps**
+- **Scheduling systems**
+- **Chatbots / AI assistants**
+- **Automation tools**
+- **DevOps scripts**
+- **Analytics dashboards**
+
+chronolite-time translates human time into timestamps your software can understand.
+
+---
+
+## 🗺 Roadmap
+
+Planned features:
+- [ ] `ago` support (`3 hours ago`)
+- [ ] `last week` / `last month`
+- [ ] Short weekdays (`mon`, `tue`)
+- [ ] Timezone parsing
+- [ ] Recurring schedules (`every 3 hours`)
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! If you have a feature request or found a bug, please open an issue.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+---
+
+## ⚖️ License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+Developed by [Adithya Gowda](https://github.com/AdityaGowda)

package/absolute.parser.js

@@ -0,0 +1,43 @@
+import {  buildSafeDate, monthIndex } from "../helper/helper.js";
+import {
+  getISODateRegex,
+  getSlashDateRegex,
+  getWordDateRegex
+} from "../utils/regex.js";
+
+export function parseAbsolute(text) {
+  if (typeof text !== "string") return null;
+
+  const input = text.trim();
+
+  // YYYY-MM-DD
+  if (getISODateRegex().test(input)) {
+    const [y, m, d] = input.split("-").map(Number);
+    return buildSafeDate(y, m - 1, d);
+  }
+
+  // 15/03/2026 or 15-03-2026
+  const slashMatch = input.match(getSlashDateRegex());
+  if (slashMatch) {
+    return buildSafeDate(
+      Number(slashMatch[3]),
+      Number(slashMatch[2]) - 1,
+      Number(slashMatch[1])
+    );
+  }
+
+  // Feb 20 2026
+  const wordMatch = input.match(getWordDateRegex());
+  if (wordMatch) {
+    const month = monthIndex(wordMatch[1]);
+    if (month === undefined) return null;
+
+    return buildSafeDate(
+      Number(wordMatch[3]),
+      month,
+      Number(wordMatch[2])
+    );
+  }
+
+  return null;
+}

package/constants.js

@@ -0,0 +1,37 @@
+export const TIME_UNITS = {
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+
+  s: 1000,
+  sec: 1000,
+  second: 1000,
+  seconds: 1000,
+
+  m: 60 * 1000,
+  min: 60 * 1000,
+  minute: 60 * 1000,
+  minutes: 60 * 1000,
+
+  h: 60 * 60 * 1000,
+  hr: 60 * 60 * 1000,
+  hour: 60 * 60 * 1000,
+  hours: 60 * 60 * 1000,
+
+  d: 24 * 60 * 60 * 1000,
+  day: 24 * 60 * 60 * 1000,
+  days: 24 * 60 * 60 * 1000,
+
+  w: 7 * 24 * 60 * 60 * 1000,
+  week: 7 * 24 * 60 * 60 * 1000,
+  weeks: 7 * 24 * 60 * 60 * 1000,
+
+  mon: 30 * 24 * 60 * 60 * 1000,
+  month: 30 * 24 * 60 * 60 * 1000,
+  months: 30 * 24 * 60 * 60 * 1000,
+
+  y: 365 * 24 * 60 * 60 * 1000,
+  yr: 365 * 24 * 60 * 60 * 1000,
+  year: 365 * 24 * 60 * 60 * 1000,
+  years: 365 * 24 * 60 * 60 * 1000
+};

package/duration.parser.js

@@ -0,0 +1,26 @@
+import { getDurationRegex } from "../utils/regex.js";
+import { TIME_UNITS } from "../utils/constants.js";
+
+export function parseDuration(text) {
+
+  if (typeof text !== "string") return null;
+  let totalMilliseconds = 0;
+  const matches = text.matchAll(getDurationRegex());
+
+  for (const match of matches) {
+    const value = parseFloat(match[2]);
+    const unit = match[3].toLowerCase();
+
+    const multiplier = TIME_UNITS[unit];
+
+    if (!multiplier) continue;
+
+    totalMilliseconds += value * multiplier;
+  }
+  if (totalMilliseconds === 0) return null;
+
+  return {
+    type: "duration",
+    milliseconds: Math.round(totalMilliseconds)
+  };
+}

package/helper.js

@@ -0,0 +1,120 @@
+
+export function buildDate(date, timeMatch) {
+  const d = new Date(date);
+  if (timeMatch) {
+    let hour = Number(timeMatch[1]);
+    const minute = Number(timeMatch[2] || 0);
+    const meridian = timeMatch[3];
+
+    if (meridian === "pm" && hour < 12) hour += 12;
+    if (meridian === "am" && hour === 12) hour = 0;
+
+    d.setHours(hour, minute, 0, 0);
+  }
+
+  return {
+    type: "relative",
+    iso: d.toISOString(),
+    unix: d.getTime()
+  };
+}
+
+export function buildSafeDate(year, month, day) {
+  if (
+    !Number.isInteger(year) ||
+    !Number.isInteger(month) ||
+    !Number.isInteger(day)
+  )
+    return null;
+
+  const d = new Date(year, month, day);
+
+  // 🚨 reject JS rollover
+  if (
+    d.getFullYear() !== year ||
+    d.getMonth() !== month ||
+    d.getDate() !== day
+  ) {
+    return null;
+  }
+
+  return buildAbsolute(d);
+}
+
+
+export function buildWeekRange(now, offset) {
+  const d = new Date(now);
+  d.setDate(d.getDate() + offset * 7);
+
+  const day = d.getDay();
+  const diff = day === 0 ? -6 : 1 - day;
+
+  const start = new Date(d);
+  start.setDate(d.getDate() + diff);
+  start.setHours(0, 0, 0, 0);
+
+  const end = new Date(start);
+  end.setDate(start.getDate() + 6);
+  end.setHours(23, 59, 59, 999);
+
+  return {
+    type: "relative-range",
+    start: start.toISOString(),
+    end: end.toISOString()
+  };
+}
+
+export function buildMonthRange(now, offset) {
+  const start = new Date(now.getFullYear(), now.getMonth() + offset, 1);
+  const end = new Date(start.getFullYear(), start.getMonth() + 1, 0);
+  end.setHours(23, 59, 59, 999);
+
+  return {
+    type: "relative-range",
+    start: start.toISOString(),
+    end: end.toISOString()
+  };
+}
+
+export function buildYearRange(now, offset) {
+  const year = now.getFullYear() + offset;
+
+  const start = new Date(year, 0, 1);
+  const end = new Date(year, 11, 31);
+  end.setHours(23, 59, 59, 999);
+
+  return {
+    type: "relative-range",
+    start: start.toISOString(),
+    end: end.toISOString()
+  };
+}
+
+export function buildAbsolute(date) {
+  const d = new Date(date);
+  d.setHours(0, 0, 0, 0);
+
+  return {
+    type: "absolute",
+    iso: d.toISOString(),
+    unix: d.getTime()
+  };
+}
+
+export function monthIndex(m) {
+  if (!m) return undefined;
+  return {
+    jan: 0, january: 0,
+    feb: 1, february: 1,
+    mar: 2, march: 2,
+    apr: 3, april: 3,
+    may: 4,
+    jun: 5, june: 5,
+    jul: 6, july: 6,
+    aug: 7, august: 7,
+    sep: 8, september: 8,
+    oct: 9, october: 9,
+    nov: 10, november: 10,
+    dec: 11, december: 11
+  }[m.toLowerCase()];
+}

package/index.js

@@ -0,0 +1,7 @@
+import { parseDuration } from "./parsers/duration.parser.js";
+import { parseRelative } from "./parsers/relative.parser.js";
+import { parseAbsolute } from "./parsers/absolute.parser.js";
+
+export function parseTime(text) {
+  return parseRelative(text) || parseDuration(text) || parseAbsolute(text);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "chronolite-time",
+  "version": "0.1.0",
+  "description": "Lightweight natural language time parser for JavaScript",
+  "main": "src/index.js",
+  "type": "module",
+   "keywords": [
+    "time",
+    "date",
+    "parser",
+    "nlp",
+    "natural-language",
+    "datetime",
+    "duration",
+    "relative-date",
+    "scheduler",
+    "human-time",
+    "time-parser",
+    "date-parser",
+    "javascript",
+    "human-readable",
+    "automation"
+  ],
+  "author": "Adithya M R",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AdityaGowda/chronolite-time.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AdityaGowda/chronolite-time/issues"
+  },
+  "homepage": "https://github.com/AdityaGowda/chronolite-time#readme"
+}

package/regex.js

@@ -0,0 +1,37 @@
+export function getDurationRegex() {
+  return /(^|[^a-zA-Z0-9.])(\d+(?:\.\d+)?)\s*(milliseconds?|ms|seconds?|Seconds?|Sec|sec|s|minutes?|min|Minutes?|Min|m|hours?|hr|Hrs?|Hr|h|days?|day|Days?|Day|d|weeks?|week|Weeks?|Week|w|years?|year|Years?|Year|y)\b/gi;
+}
+
+
+
+// Relative regex
+
+export function getTimeRegex() {
+  return /\bat\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\b/i;
+}
+
+export function getInRegex() {
+  return /^in\s+(\d+(?:\.\d+)?)\s+(seconds?|minutes?|hours?|days?|weeks?|months?|years?)/i;
+}
+
+export function getWeekdayRegex() {
+  return /^(next|this)\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)/i;
+}
+
+
+// -------- ABSOLUTE DATE REGEX --------
+
+// 2026-03-15
+export function getISODateRegex() {
+  return /^\d{4}-\d{2}-\d{2}$/;
+}
+
+//  dd/mm/yyyy or dd-mm-yyyy
+export function getSlashDateRegex() {
+  return /^(\d{1,2})[\/-](\d{1,2})[\/-](\d{4})$/;
+}
+
+// format: "Month day, year" (e.g., "January 12, 2026" or "Jan 12 2026")
+export function getWordDateRegex() {
+  return /^(jan|january|feb|february|mar|march|apr|april|may|jun|june|jul|july|aug|august|sep|september|oct|october|nov|november|dec|december)\s+(\d{1,2}),?\s+(\d{4})$/i;
+}

package/relative.parser.js

@@ -0,0 +1,93 @@
+import { buildDate, buildMonthRange, buildWeekRange, buildYearRange } from "../helper/helper.js";
+import { getInRegex,getTimeRegex,getWeekdayRegex } from "../utils/regex.js";
+
+const WEEKDAYS = {
+  sunday: 0,
+  monday: 1,
+  tuesday: 2,
+  wednesday: 3,
+  thursday: 4,
+  friday: 5,
+  saturday: 6
+};
+
+const UNIT_SETTERS = {
+  second: (d, v) => d.setSeconds(d.getSeconds() + v),
+  minute: (d, v) => d.setMinutes(d.getMinutes() + v),
+  hour: (d, v) => d.setHours(d.getHours() + v),
+  day: (d, v) => d.setDate(d.getDate() + v),
+  week: (d, v) => d.setDate(d.getDate() + v * 7),
+  month: (d, v) => d.setMonth(d.getMonth() + v),
+  year: (d, v) => d.setFullYear(d.getFullYear() + v)
+};
+
+export function parseRelative(text) {
+  if (typeof text !== "string") return null;
+
+  const input = text.toLowerCase().trim();
+  const now = new Date();
+
+  const timeMatch = input.match(getTimeRegex());
+
+  // -------- keywords --------
+  const keywordMap = {
+    today: 0,
+    tomorrow: 1,
+    yesterday: -1
+  };
+
+  if (keywordMap[input] !== undefined) {
+    const d = new Date(now);
+    d.setDate(d.getDate() + keywordMap[input]);
+    return buildDate(d, timeMatch);
+  }
+
+  // -------- in X units --------
+  const inMatch = input.match(getInRegex());
+
+  if (inMatch) {
+    const value = Number(inMatch[1]);
+    const unit = inMatch[2].replace(/s$/, "");
+
+    if (!Number.isFinite(value)) return null;
+    if (!UNIT_SETTERS[unit]) return null;
+
+    const d = new Date(now);
+    UNIT_SETTERS[unit](d, value);
+
+    return buildDate(d, timeMatch);
+  }
+
+  // -------- ranges --------
+
+  const ranges = {
+    "this week": () => buildWeekRange(now, 0),
+    "next week": () => buildWeekRange(now, 1),
+    "this month": () => buildMonthRange(now, 0),
+    "next month": () => buildMonthRange(now, 1),
+    "this year": () => buildYearRange(now, 0),
+    "next year": () => buildYearRange(now, 1)
+  };
+
+  if (ranges[input]) return ranges[input]();
+
+  // -------- weekdays --------
+
+  const weekdayMatch = input.match(getWeekdayRegex());
+
+  if (weekdayMatch) {
+    const [, modifier, weekday] = weekdayMatch;
+
+    const target = WEEKDAYS[weekday];
+    const d = new Date(now);
+
+    let diff = target - d.getDay();
+    if (modifier === "next" || diff <= 0) diff += 7;
+
+    d.setDate(d.getDate() + diff);
+
+    return buildDate(d, timeMatch);
+  }
+
+  return null;
+}

package/src/helper/helper.js

@@ -0,0 +1,120 @@
+
+export function buildDate(date, timeMatch) {
+  const d = new Date(date);
+  if (timeMatch) {
+    let hour = Number(timeMatch[1]);
+    const minute = Number(timeMatch[2] || 0);
+    const meridian = timeMatch[3];
+
+    if (meridian === "pm" && hour < 12) hour += 12;
+    if (meridian === "am" && hour === 12) hour = 0;
+
+    d.setHours(hour, minute, 0, 0);
+  }
+
+  return {
+    type: "relative",
+    iso: d.toISOString(),
+    unix: d.getTime()
+  };
+}
+
+export function buildSafeDate(year, month, day) {
+  if (
+    !Number.isInteger(year) ||
+    !Number.isInteger(month) ||
+    !Number.isInteger(day)
+  )
+    return null;
+
+  const d = new Date(year, month, day);
+
+  // 🚨 reject JS rollover
+  if (
+    d.getFullYear() !== year ||
+    d.getMonth() !== month ||
+    d.getDate() !== day
+  ) {
+    return null;
+  }
+
+  return buildAbsolute(d);
+}
+
+
+export function buildWeekRange(now, offset) {
+  const d = new Date(now);
+  d.setDate(d.getDate() + offset * 7);
+
+  const day = d.getDay();
+  const diff = day === 0 ? -6 : 1 - day;
+
+  const start = new Date(d);
+  start.setDate(d.getDate() + diff);
+  start.setHours(0, 0, 0, 0);
+
+  const end = new Date(start);
+  end.setDate(start.getDate() + 6);
+  end.setHours(23, 59, 59, 999);
+
+  return {
+    type: "relative-range",
+    start: start.toISOString(),
+    end: end.toISOString()
+  };
+}
+
+export function buildMonthRange(now, offset) {
+  const start = new Date(now.getFullYear(), now.getMonth() + offset, 1);
+  const end = new Date(start.getFullYear(), start.getMonth() + 1, 0);
+  end.setHours(23, 59, 59, 999);
+
+  return {
+    type: "relative-range",
+    start: start.toISOString(),
+    end: end.toISOString()
+  };
+}
+
+export function buildYearRange(now, offset) {
+  const year = now.getFullYear() + offset;
+
+  const start = new Date(year, 0, 1);
+  const end = new Date(year, 11, 31);
+  end.setHours(23, 59, 59, 999);
+
+  return {
+    type: "relative-range",
+    start: start.toISOString(),
+    end: end.toISOString()
+  };
+}
+
+export function buildAbsolute(date) {
+  const d = new Date(date);
+  d.setHours(0, 0, 0, 0);
+
+  return {
+    type: "absolute",
+    iso: d.toISOString(),
+    unix: d.getTime()
+  };
+}
+
+export function monthIndex(m) {
+  if (!m) return undefined;
+  return {
+    jan: 0, january: 0,
+    feb: 1, february: 1,
+    mar: 2, march: 2,
+    apr: 3, april: 3,
+    may: 4,
+    jun: 5, june: 5,
+    jul: 6, july: 6,
+    aug: 7, august: 7,
+    sep: 8, september: 8,
+    oct: 9, october: 9,
+    nov: 10, november: 10,
+    dec: 11, december: 11
+  }[m.toLowerCase()];
+}

package/src/index.js

@@ -0,0 +1,7 @@
+import { parseDuration } from "./parsers/duration.parser.js";
+import { parseRelative } from "./parsers/relative.parser.js";
+import { parseAbsolute } from "./parsers/absolute.parser.js";
+
+export function parseTime(text) {
+  return parseRelative(text) || parseDuration(text) || parseAbsolute(text);
+}

package/src/parsers/absolute.parser.js

@@ -0,0 +1,43 @@
+import {  buildSafeDate, monthIndex } from "../helper/helper.js";
+import {
+  getISODateRegex,
+  getSlashDateRegex,
+  getWordDateRegex
+} from "../utils/regex.js";
+
+export function parseAbsolute(text) {
+  if (typeof text !== "string") return null;
+
+  const input = text.trim();
+
+  // YYYY-MM-DD
+  if (getISODateRegex().test(input)) {
+    const [y, m, d] = input.split("-").map(Number);
+    return buildSafeDate(y, m - 1, d);
+  }
+
+  // 15/03/2026 or 15-03-2026
+  const slashMatch = input.match(getSlashDateRegex());
+  if (slashMatch) {
+    return buildSafeDate(
+      Number(slashMatch[3]),
+      Number(slashMatch[2]) - 1,
+      Number(slashMatch[1])
+    );
+  }
+
+  // Feb 20 2026
+  const wordMatch = input.match(getWordDateRegex());
+  if (wordMatch) {
+    const month = monthIndex(wordMatch[1]);
+    if (month === undefined) return null;
+
+    return buildSafeDate(
+      Number(wordMatch[3]),
+      month,
+      Number(wordMatch[2])
+    );
+  }
+
+  return null;
+}

package/src/parsers/duration.parser.js

@@ -0,0 +1,26 @@
+import { getDurationRegex } from "../utils/regex.js";
+import { TIME_UNITS } from "../utils/constants.js";
+
+export function parseDuration(text) {
+
+  if (typeof text !== "string") return null;
+  let totalMilliseconds = 0;
+  const matches = text.matchAll(getDurationRegex());
+
+  for (const match of matches) {
+    const value = parseFloat(match[2]);
+    const unit = match[3].toLowerCase();
+
+    const multiplier = TIME_UNITS[unit];
+
+    if (!multiplier) continue;
+
+    totalMilliseconds += value * multiplier;
+  }
+  if (totalMilliseconds === 0) return null;
+
+  return {
+    type: "duration",
+    milliseconds: Math.round(totalMilliseconds)
+  };
+}

package/src/parsers/relative.parser.js

@@ -0,0 +1,93 @@
+import { buildDate, buildMonthRange, buildWeekRange, buildYearRange } from "../helper/helper.js";
+import { getInRegex,getTimeRegex,getWeekdayRegex } from "../utils/regex.js";
+
+const WEEKDAYS = {
+  sunday: 0,
+  monday: 1,
+  tuesday: 2,
+  wednesday: 3,
+  thursday: 4,
+  friday: 5,
+  saturday: 6
+};
+
+const UNIT_SETTERS = {
+  second: (d, v) => d.setSeconds(d.getSeconds() + v),
+  minute: (d, v) => d.setMinutes(d.getMinutes() + v),
+  hour: (d, v) => d.setHours(d.getHours() + v),
+  day: (d, v) => d.setDate(d.getDate() + v),
+  week: (d, v) => d.setDate(d.getDate() + v * 7),
+  month: (d, v) => d.setMonth(d.getMonth() + v),
+  year: (d, v) => d.setFullYear(d.getFullYear() + v)
+};
+
+export function parseRelative(text) {
+  if (typeof text !== "string") return null;
+
+  const input = text.toLowerCase().trim();
+  const now = new Date();
+
+  const timeMatch = input.match(getTimeRegex());
+
+  // -------- keywords --------
+  const keywordMap = {
+    today: 0,
+    tomorrow: 1,
+    yesterday: -1
+  };
+
+  if (keywordMap[input] !== undefined) {
+    const d = new Date(now);
+    d.setDate(d.getDate() + keywordMap[input]);
+    return buildDate(d, timeMatch);
+  }
+
+  // -------- in X units --------
+  const inMatch = input.match(getInRegex());
+
+  if (inMatch) {
+    const value = Number(inMatch[1]);
+    const unit = inMatch[2].replace(/s$/, "");
+
+    if (!Number.isFinite(value)) return null;
+    if (!UNIT_SETTERS[unit]) return null;
+
+    const d = new Date(now);
+    UNIT_SETTERS[unit](d, value);
+
+    return buildDate(d, timeMatch);
+  }
+
+  // -------- ranges --------
+
+  const ranges = {
+    "this week": () => buildWeekRange(now, 0),
+    "next week": () => buildWeekRange(now, 1),
+    "this month": () => buildMonthRange(now, 0),
+    "next month": () => buildMonthRange(now, 1),
+    "this year": () => buildYearRange(now, 0),
+    "next year": () => buildYearRange(now, 1)
+  };
+
+  if (ranges[input]) return ranges[input]();
+
+  // -------- weekdays --------
+
+  const weekdayMatch = input.match(getWeekdayRegex());
+
+  if (weekdayMatch) {
+    const [, modifier, weekday] = weekdayMatch;
+
+    const target = WEEKDAYS[weekday];
+    const d = new Date(now);
+
+    let diff = target - d.getDay();
+    if (modifier === "next" || diff <= 0) diff += 7;
+
+    d.setDate(d.getDate() + diff);
+
+    return buildDate(d, timeMatch);
+  }
+
+  return null;
+}

package/src/utils/constants.js

@@ -0,0 +1,37 @@
+export const TIME_UNITS = {
+  ms: 1,
+  millisecond: 1,
+  milliseconds: 1,
+
+  s: 1000,
+  sec: 1000,
+  second: 1000,
+  seconds: 1000,
+
+  m: 60 * 1000,
+  min: 60 * 1000,
+  minute: 60 * 1000,
+  minutes: 60 * 1000,
+
+  h: 60 * 60 * 1000,
+  hr: 60 * 60 * 1000,
+  hour: 60 * 60 * 1000,
+  hours: 60 * 60 * 1000,
+
+  d: 24 * 60 * 60 * 1000,
+  day: 24 * 60 * 60 * 1000,
+  days: 24 * 60 * 60 * 1000,
+
+  w: 7 * 24 * 60 * 60 * 1000,
+  week: 7 * 24 * 60 * 60 * 1000,
+  weeks: 7 * 24 * 60 * 60 * 1000,
+
+  mon: 30 * 24 * 60 * 60 * 1000,
+  month: 30 * 24 * 60 * 60 * 1000,
+  months: 30 * 24 * 60 * 60 * 1000,
+
+  y: 365 * 24 * 60 * 60 * 1000,
+  yr: 365 * 24 * 60 * 60 * 1000,
+  year: 365 * 24 * 60 * 60 * 1000,
+  years: 365 * 24 * 60 * 60 * 1000
+};

package/src/utils/regex.js

@@ -0,0 +1,37 @@
+export function getDurationRegex() {
+  return /(^|[^a-zA-Z0-9.])(\d+(?:\.\d+)?)\s*(milliseconds?|ms|seconds?|Seconds?|Sec|sec|s|minutes?|min|Minutes?|Min|m|hours?|hr|Hrs?|Hr|h|days?|day|Days?|Day|d|weeks?|week|Weeks?|Week|w|years?|year|Years?|Year|y)\b/gi;
+}
+
+
+
+// Relative regex
+
+export function getTimeRegex() {
+  return /\bat\s+(\d{1,2})(?::(\d{2}))?\s*(am|pm)?\b/i;
+}
+
+export function getInRegex() {
+  return /^in\s+(\d+(?:\.\d+)?)\s+(seconds?|minutes?|hours?|days?|weeks?|months?|years?)/i;
+}
+
+export function getWeekdayRegex() {
+  return /^(next|this)\s+(monday|tuesday|wednesday|thursday|friday|saturday|sunday)/i;
+}
+
+
+// -------- ABSOLUTE DATE REGEX --------
+
+// 2026-03-15
+export function getISODateRegex() {
+  return /^\d{4}-\d{2}-\d{2}$/;
+}
+
+//  dd/mm/yyyy or dd-mm-yyyy
+export function getSlashDateRegex() {
+  return /^(\d{1,2})[\/-](\d{1,2})[\/-](\d{4})$/;
+}
+
+// format: "Month day, year" (e.g., "January 12, 2026" or "Jan 12 2026")
+export function getWordDateRegex() {
+  return /^(jan|january|feb|february|mar|march|apr|april|may|jun|june|jul|july|aug|august|sep|september|oct|october|nov|november|dec|december)\s+(\d{1,2}),?\s+(\d{4})$/i;
+}

package/test.js

@@ -0,0 +1,69 @@
+import { parseTime } from "./src/index.js";
+import { generateTestCases } from "./tests/use-cases.test.js";
+
+const cases = generateTestCases();
+
+console.log("Total cases:", cases.length);
+
+// ---------------- Counters ----------------
+
+let durationCount = 0;
+let relativeCount = 0;
+let absoluteCount = 0;
+let nullCount = 0;
+let errorCount = 0;
+
+// ---------------- Performance ----------------
+
+console.time("chronolite-time Parse");
+
+// ---------------- Run Tests ----------------
+
+cases.forEach((input) => {
+  try {
+    const result = parseTime(input);
+
+    if (!result) {
+      nullCount++;
+      return;
+    }
+
+    if (result.type === "duration") durationCount++;
+    else if (result.type === "absolute") absoluteCount++;
+    else if (
+      result.type === "relative" ||
+      result.type === "relative-range"
+    )
+      relativeCount++;
+    else {
+      console.error("❌ Unknown result type:", input, result);
+      errorCount++;
+    }
+  } catch (e) {
+    console.error("💥 Exception for:", input, e.message);
+    errorCount++;
+  }
+});
+
+console.timeEnd("chronolite-time Parse");
+
+// ---------------- Summary ----------------
+
+console.log("\n===== SUMMARY =====");
+console.log("Duration:", durationCount);
+console.log("Relative:", relativeCount);
+console.log("Absolute:", absoluteCount);
+console.log("Null:", nullCount);
+console.log("Errors:", errorCount);
+
+// ---------------- Basic Quality Check ----------------
+
+if (errorCount === 0) {
+  console.log("\n✅ No runtime errors.");
+}
+
+if (nullCount > cases.length * 0.6) {
+  console.warn("\n⚠️ High null rate — many formats unsupported.");
+}
+
+console.log("\nDone.");

package/tests/use-cases.test.js

@@ -0,0 +1,137 @@
+export function generateTestCases() {
+  const cases = [];
+
+  // ---------------- DURATION ----------------
+
+  const nums = [0, 0.1, 0.5, 1, 1.5, 2, 3, 5, 7, 10, 15, 20, 25, 30, 45, 50, 100];
+  const units = [
+    "second", "seconds", "sec", "secs",
+    "minute", "minutes", "min", "mins",
+    "hour", "hours", "hr", "hrs",
+    "day", "days", "d",
+    "week", "weeks", "w",
+    "month", "months", "mo",
+    "year", "years", "y"
+  ];
+
+  nums.forEach(n => {
+    units.forEach(u => {
+      cases.push(`${n} ${u}`);
+      cases.push(`${n}${u[0]}`);
+      cases.push(`${n} ${u} and ${n} ${u}`);
+      cases.push(`${n} ${u}, ${n} ${u}`);
+    });
+  });
+
+  // Mixed durations
+  for (let i = 1; i <= 200; i++) {
+    cases.push(`${i} hours ${i} minutes`);
+    cases.push(`${i}h ${i}m`);
+    cases.push(`${i} days ${i} hours`);
+    cases.push(`${i} weeks ${i} days`);
+  }
+
+  // ---------------- RELATIVE ----------------
+
+  const relatives = [
+    "today",
+    "tomorrow",
+    "yesterday",
+    "this week",
+    "next week",
+    "last week",
+    "this month",
+    "next month",
+    "last month",
+    "this year",
+    "next year",
+    "last year",
+    "now"
+  ];
+
+  relatives.forEach(r => cases.push(r));
+
+  for (let i = 1; i <= 300; i++) {
+    cases.push(`in ${i} seconds`);
+    cases.push(`in ${i} minutes`);
+    cases.push(`in ${i} hours`);
+    cases.push(`in ${i} days`);
+    cases.push(`in ${i} weeks`);
+    cases.push(`${i} hours ago`);
+    cases.push(`${i} days ago`);
+  }
+
+  const weekdays = [
+    "monday","tuesday","wednesday",
+    "thursday","friday","saturday","sunday",
+    "mon", "tue", "wed", "thu", "fri", "sat", "sun"
+  ];
+
+  weekdays.forEach(d => {
+    cases.push(`next ${d}`);
+    cases.push(`this ${d}`);
+    cases.push(`last ${d}`);
+    cases.push(`next ${d} at 5pm`);
+    cases.push(`this ${d} at 10:30am`);
+    cases.push(`${d} 5pm`);
+  });
+
+  // ---------------- ABSOLUTE ----------------
+
+  for (let y = 2000; y <= 2050; y += 2) {
+    for (let m = 1; m <= 12; m++) {
+      for (let d = 1; d <= 10; d++) {
+        cases.push(`${y}-${String(m).padStart(2,"0")}-${String(d).padStart(2,"0")}`);
+        cases.push(`${d}/${m}/${y}`);
+        cases.push(`${m}-${d}-${y}`);
+      }
+    }
+  }
+
+  const months = [
+    "Jan","Feb","Mar","Apr","May","Jun","Jul","Aug","Sep","Oct","Nov","Dec",
+    "January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"
+  ];
+
+  months.forEach(m => {
+    for (let d = 1; d <= 20; d++) {
+      cases.push(`${m} ${d} 2026`);
+      cases.push(`${d} ${m} 2026`);
+      cases.push(`${m} ${d}`);
+    }
+  });
+
+  // Time variations
+  for (let h = 0; h < 24; h++) {
+    cases.push(`${h}:00`);
+    cases.push(`${h}:30`);
+    if (h > 0 && h <= 12) {
+      cases.push(`${h}am`);
+      cases.push(`${h}pm`);
+    }
+  }
+
+  // ---------------- INVALID ----------------
+
+  const invalids = [
+    "",
+    " ",
+    "abc",
+    "1e3h",
+    "31/02/2026",
+    "2026-02-31",
+    "15/13/2026",
+    "foo bar",
+    "-5 hours",
+    "1..5h",
+    "@@@",
+    "2026/13/45",
+    "yesterday tomorrow",
+    "infinity hours"
+  ];
+
+  invalids.forEach(i => cases.push(i));
+
+  return cases;
+}
+