AniccaJS ⏳

AniccaJS is a high-performance, lightweight JavaScript date library designed for modern applications. Named after the concept of impermanence, it emphasizes an immutable approach to date manipulation, ensuring that your original data remains untouched while providing powerful tools for formatting, business logic, and social-style time.

🚀 Quick Start

Installation

npm install aniccajs

Basic Setup

import anicca from "aniccajs";

// Initialize with current time
const now = anicca();

// Human-friendly formatting
console.log(now.format("dddd, MMMM D, YYYY"));
// Output: Saturday, February 14, 2026

🛠 Usage Examples

1. Immutability & Manipulation

Every operation returns a new instance.

const today = anicca("2026-02-14");
const nextMonth = today.add(1, "month");

console.log(today.format("YYYY-MM-DD")); // 2026-02-14
console.log(nextMonth.format("YYYY-MM-DD")); // 2026-03-14

2. Social Media "Time Ago"

const postDate = anicca("2026-02-14T10:00:00");
console.log(postDate.ago()); // "11 hours ago"
console.log(anicca("Asia/Yangon").ago("2026-02-14T10:00:00")); // 11 hours ago

3. Business Logic

const deadline = anicca("2026-02-20");
console.log(deadline.isWeekend()); // false
console.log(deadline.isBusinessDay()); // true
console.log(deadline.quarter()); // 1 (Q1)

📖 Full API Reference

1. Initialization

| Method | Description | | ----------------------- | ---------------------------------------------------------------------- | | anicca() | Returns an instance with the current local system time. | | anicca(dateString) | Parses a standard date string (e.g., ISO 8601). | | anicca(timestamp) | Parses a Unix timestamp in milliseconds. | | anicca("Asia/Yangon") | Returns an instance with the current time in a specific IANA timezone. |

2. Display & Formatting

| Method | Return | Description | | -------------------- | --------- | ------------------------------------------------------------------------ | | .format(pattern) | String | Formats the date. Tokens: YYYY, MMMM, DD, dddd, HH, mm, A. | | .ago(compareDate?) | String | Returns relative time. Compares to now if no parameter is provided. | | .toDate() | Date | Returns the native JavaScript Date object. | | .valueOf() | Number | Returns the timestamp in milliseconds. | | .isValid() | Boolean | Validates if the date input is a real date. |

3. Manipulation

| Method | Return | Description | | ---------------------- | ---------- | -------------------------------------------------------------------------- | | .add(val, unit) | Instance | Adds time. Units: year, month, day, hour, minute, second. | | .subtract(val, unit) | Instance | Subtracts time based on units. | | .startOf(unit) | Instance | Resets time to the start of the unit (e.g., month sets to 1st at 00:00). |

4. Comparison & Queries

| Method | Return | Description | | ------------------ | --------- | ------------------------------------------------------------------ | | .isToday() | Boolean | Returns true if the date is today. | | .isTomorrow() | Boolean | Returns true if the date is tomorrow. | | .isYesterday() | Boolean | Returns true if the date was yesterday. | | .isWeekend() | Boolean | Returns true for Saturday or Sunday. | | .isBusinessDay() | Boolean | Returns true for Monday through Friday. | | .isLeapYear() | Boolean | Returns true if the year is a leap year. | | .isBetween(s, e) | Boolean | Returns true if date falls within the start (s) and end (e) range. |

5. Business & Calendar Logic

| Method | Return | Description | | ---------------------- | -------- | ----------------------------------------------------------------- | | .week() | Number | Returns the ISO week number (1-53). | | .daysInMonth() | Number | Returns the number of days in the current month. | | .quarter() | Number | Returns the quarter of the year (1-4). | | .fiscalYear(start) | Number | Returns fiscal year (Default start: 3 for April). | | .diffBusinessDays(t) | Number | Calculates the number of working days between now and target (t). |

6. Static Methods

| Method | Description | | ----------------------- | ----------------------------------------------------------------------------- | | anicca.range(s, e) | Generates an array of Anicca instances for every day between start and end. | | anicca.duration(v, u) | Converts a value and unit into raw milliseconds. |

🔠 Formatting Tokens Reference

| Token | Output | Description | | -------- | -------- | ---------------- | | YYYY | 2026 | 4-digit year | | MMMM | February | Full month name | | MMM | Feb | Short month name | | DD | 14 | 2-digit day | | dddd | Saturday | Full day name | | HH | 21 | 24-hour clock | | mm | 15 | Minutes | | A | PM/AM | Meridiem |

⚖️ License

MIT © 2026 AniccaJS