# DaySafe — Developer & LLM Documentation

> DaySafe is a lightweight, zero-dependency TypeScript library for predictable, timezone-safe calendar date operations.

- Website: https://daysafe.ajitdev.com/
- Interactive Playground: https://daysafe.ajitdev.com/playground
- Documentation: https://daysafe.ajitdev.com/docs/getting-started
- API Reference: https://daysafe.ajitdev.com/docs/api-reference
- Timezone Guide: https://daysafe.ajitdev.com/docs/timezone-safety
- npm: https://www.npmjs.com/package/daysafe
- GitHub: https://github.com/ajitdev01/daysafe
- License: MIT License (https://github.com/ajitdev01/daysafe/blob/master/LICENSE)
- Maintainer: Ajit Kumar (@AjitDev01) — https://www.ajitdev.com/

## Core Problem
JavaScript's native `Date` object interprets ISO date strings like `"2026-11-04"` as UTC midnight (`2026-11-04T00:00:00Z`). In timezones behind UTC (such as UTC-5 EST), formatting this date in local time displays `"2026-11-03"`, resulting in silent date corruption. DaySafe treats calendar dates as pure civil dates (Year, Month, Day) without timezone offsets, leap second distortions, or daylight saving shifts.

## Installation
```bash
npm install daysafe
# or
pnpm add daysafe
# or
yarn add daysafe
```

## Key API Functions
- `parseDateSafe(input: string | DateComponents): ISODateString`: Strict parsing with validation.
- `formatDateSafe(date: ISODateString, pattern: string): string`: Deterministic string formatting.
- `addDaysSafe(date: ISODateString, amount: number): ISODateString`: Day addition without timezone jumps.
- `subDaysSafe(date: ISODateString, amount: number): ISODateString`: Day subtraction.
- `addMonthsSafe(date: ISODateString, amount: number): ISODateString`: Safe month addition with end-of-month pinning.
- `subMonthsSafe(date: ISODateString, amount: number): ISODateString`: Safe month subtraction.
- `diffInDaysSafe(a: ISODateString, b: ISODateString): number`: Absolute or signed day difference.
- `isLeapYearSafe(year: number): boolean`: Strict Gregorian leap year evaluation.
- `isWeekendSafe(date: ISODateString)` / `isWeekdaySafe(date: ISODateString)`: Day-of-week checks.
- `isSameDaySafe(a: ISODateString, b: ISODateString): boolean`: Equality check.

## Key Principles
1. Zero Runtime Dependencies.
2. 100% In-Browser & Local Execution.
3. Branded TypeScript Types (`ISODateString`).
4. Deterministic Civil Calendar Math.

## Digital Ecosystem
- Skelcraft (Customizable React Skeleton UI Library): https://skelcraft.ajitdev.com/
- AjitDev APIs (Developer microservices and tools): https://api.ajitdev.com/
- Next.js Projects (Next.js boilerplates and architectures): https://next.ajitdev.com/
- Ajit Kumar Portfolio: https://www.ajitdev.com/
- GitHub: https://github.com/ajitdev01
- DEV Community: https://dev.to/ajitdev01
- Medium: https://medium.com/@ajitdev01