ngx-chronox

A complete date toolkit for Angular Helpers • Pipes • Validators • Types • Constants Angular v14+ compatible

ngx-chronox simplifies date handling across your Angular application with:

• Static utility helpers
• Smart relative formatting
• Angular pipes for templates
• Reactive form validators
• Strong typing & utilities
• Locale-aware formatting
• Multiple date input formats

Installation

npm install @fagon/ngx-chronox

Import

import { ChronoxHelper } from "ngx-chronox";

Library Building Blocks

Constants

import { CONSTANTS } from "ngx-chronox";

CONSTANTS.ONE_SECOND_IN_MILLISECONDS // 1000 CONSTANTS.ONE_MINUTE_IN_MILLISECONDS // 60000 CONSTANTS.ONE_HOUR_IN_MILLISECONDS // 3600000 CONSTANTS.TWENTY_FOUR_HOURS_IN_MILLISECONDS // 86400000 CONSTANTS.FOURTY_EIGHT_HOURS_IN_MILLISECONDS // 172800000 CONSTANTS.DEFAULT_DATE_FORMAT // 'd MMM, yyyy'

Example

const timeout = 5 \* CONSTANTS.ONE_MINUTE_IN_MILLISECONDS;

RegExps

import { RegExps } from "ngx-chronox";

MONTH_YEAR_REGEX

Validates MM-YYYY format.

RegExps.MONTH_YEAR_REGEX.test('02-2026'); // true RegExps.MONTH_YEAR_REGEX.test('2-2026'); // false

Example: Form Validation

if (!RegExps.MONTH_YEAR_REGEX.test(input)) {
  console.log("Invalid format. Use MM-YYYY");
}

Types & Interfaces

DateStruct

export interface DateStruct {
  year: number;
  month: number;
  day: number;
}

MonthYear

export type MonthYear = {
  year: number;
  month: number;
};

Usage Example

const birthday: DateStruct = {
  year: 2000,
  month: 5,
  day: 12,
};

const expiry: MonthYear = {
  year: 2027,
  month: 11,
};

Global Locale

Default: 'en-US'

Change globally:

ChronoxHelper.setLocale('en-GB'); 🧠 Supported Date Inputs

All helpers, pipes, and validators accept:

✔ Date ✔ Timestamp ✔ ISO string ✔ { year, month, day } ✔ { year, month }

ChronoxHelper (Core Utility)

normalizeDate()

Converts supported formats to a native Date.

Examples ChronoxHelper.normalizeDate(); ChronoxHelper.normalizeDate('2026-02-01'); ChronoxHelper.normalizeDate(1706745600000);

ChronoxHelper.normalizeDate({ year: 2026, month: 2, day: 1 });

ChronoxHelper.normalizeDate({ year: 2026, month: 2 }); // → last day of February

convertToDateStruct()

const struct = ChronoxHelper.convertToDateStruct();
console.log(struct); // { year: 2026, month: 2, day: 27 }

Convert user input

const struct = ChronoxHelper.convertToDateStruct("2026-02-01");

addToDate()

ChronoxHelper.addToDate(7, 'day'); ChronoxHelper.addToDate(2, 'month'); ChronoxHelper.addToDate(30, 'minute'); ChronoxHelper.addToDate(1, 'hour', '2026-02-01');

Real-world: subscription expiry

const expiry = ChronoxHelper.addToDate(1, "month", startDate);

subtractFromDate()

ChronoxHelper.subtractFromDate(7, 'day'); ChronoxHelper.subtractFromDate(1, 'month'); ChronoxHelper.subtractFromDate(15, 'minute');

Example: show last login window

const lastWeek = ChronoxHelper.subtractFromDate(7, "day");

calculateDaysBetweenDates()

ChronoxHelper.calculateDaysBetweenDates('2026-02-01', '2026-02-10'); // "9 days"

Booking duration example

const stay = ChronoxHelper.calculateDaysBetweenDates(checkIn, checkOut);

formatDate()

Uses Angular DatePipe.

ChronoxHelper.formatDate(new Date()); ChronoxHelper.formatDate(new Date(), 'dd/MM/yyyy'); ChronoxHelper.formatDate(new Date(), 'longDate', 'fr-FR');

Example

const label = ChronoxHelper.formatDate(invoiceDate, "MMM d");

smartDateFormat()

Auto Mode ChronoxHelper.smartDateFormat(messageDate);

Outputs:

• few seconds ago
• 3 minutes ago
• 5 hours ago
• yesterday
• today
• tomorrow

formatted date

Unit Mode ChronoxHelper.smartDateFormat(date, 'day'); ChronoxHelper.smartDateFormat(date, 'month', 'MMMM yyyy');

compareDateToNow()

ChronoxHelper.compareDateToNow('2026-01-01', 'day'); // days ago ChronoxHelper.compareDateToNow('2025-01-01', 'month'); // months ago

Date Comparisons

1. ChronoxHelper.equals(a, b);
2. ChronoxHelper.before(a, b);
3. ChronoxHelper.after(a, b);
4. ChronoxHelper.equalsOrAfter(a, b);
5. ChronoxHelper.beforeOrEquals(a, b);
6. ChronoxHelper.isSameDay(a, b);

Example

if (ChronoxHelper.before(expiry, new Date())) {
  console.log("Expired");
}

Angular Pipes

chronoxDate Pipe

Formats a date.

Template

{{ orderDate | chronoxDate }}
{{ orderDate | chronoxDate:'dd/MM/yyyy' }}

Component orderDate = new Date();

chronoxDaysDiff Pipe

Difference between two dates.

{{ startDate | chronoxDaysDiff:endDate }}

Example startDate = '2026-02-01'; endDate = '2026-02-10';

Output: 9 days

chronoxSmartDate Pipe

Smart relative formatting.

{{ postDate | chronoxSmartDate }}
{{ postDate | chronoxSmartDate:'day' }}
{{ postDate | chronoxSmartDate:'month':'MMMM yyyy' }}

Example Feed UI

<li *ngFor="let post of posts">{{ post.createdAt | chronoxSmartDate }}</li>

Validators

DateRangeOrderValidatorFactory

Ensures start date is before end date.

Setup

constructor(
private rangeValidator: DateRangeOrderValidatorFactory
) {}
//Apply
this.form = this.fb.group(
	{
		start: [''],
		end: ['']
	},
	{
	validators: this.rangeValidator.createValidator('start', 'end')
	}
);

Template

<div *ngIf="form.errors?.startDateAfterEndDate">End date must be after start date</div>

dateTimeValidator

Ensures valid date and time input.

dateControl = new FormControl('', dateTimeValidator);

maxDateRangeDifferenceValidator

Restricts date range length.

this.form = this.fb.group(
  {
    start: [""],
    end: [""],
  },
  {
    validators: maxDateRangeDifferenceValidator("start", "end", 3),
  },
);

Use Case

• booking limits
• reporting filters
• subscription windows

noFutureDateValidator

Prevents future dates.

dob = new FormControl("", noFutureDateValidator);

Example

• birth dates
• past event entries
• compliance forms

COMPLETE USAGE EXAMPLES

Chat App Timestamp

<span>{{ message.time | chronoxSmartDate }}</span>

Booking Duration

duration = ChronoxHelper.calculateDaysBetweenDates(booking.start, booking.end);

Payment Expiry Check

if (ChronoxHelper.before(cardExpiry, new Date())) {
  alert("Card expired");
}

Prevent Future Birth Date

birthDate = new FormControl("", noFutureDateValidator);

Subscription Expiry Calculation

nextBilling = ChronoxHelper.addToDate(1, "month", today);

Validate Month-Year Input

if (!RegExps.MONTH_YEAR_REGEX.test(value)) {
  throw new Error("Format must be MM-YYYY");
}

Activity Feed UI

<li *ngFor="let activity of activities">{{ activity.date | chronoxSmartDate }}</li>

Report Filter Form

this.form = this.fb.group(
  {
    from: [""],
    to: [""],
  },
  {
    validators: maxDateRangeDifferenceValidator("from", "to", 6),
  },
);

Best Practices

• Use pipes for UI formatting
• Use helpers for business logic
• Normalize external dates before storage
• Apply validators at FormGroup level for date relationships
• Use smartDateFormat for user-friendly timestamps

📄 License

MIT © Fagon Technologies