https://github.com/imevanc/chronobox
A TypeScript library for date manipulation
https://github.com/imevanc/chronobox
dates jest npm prettier semantic-release ts-jest ts-node typescript
Last synced: 11 months ago
JSON representation
A TypeScript library for date manipulation
- Host: GitHub
- URL: https://github.com/imevanc/chronobox
- Owner: imevanc
- License: mit
- Created: 2025-01-18T17:13:48.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-13T19:50:38.000Z (about 1 year ago)
- Last Synced: 2025-03-13T20:36:48.576Z (about 1 year ago)
- Topics: dates, jest, npm, prettier, semantic-release, ts-jest, ts-node, typescript
- Language: TypeScript
- Homepage:
- Size: 255 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ChronoBox
ChronoBox is a lightweight, versatile, and easy-to-use TypeScript library for handling date manipulation and formatting. It provides a powerful API for adding, subtracting, comparing, and formatting dates.
## 🚀 Features
- Add and subtract time units (e.g., days, weeks, months, years) with ease
- Calculate differences between dates in various time units
- Retrieve individual components of a date
- Format dates using custom formats
- Built-in validation for date inputs
- Fully written in TypeScript with strong type safety
## 📦 Installation
```bash
npm install chronobox
```
## 📖 API Reference
### ChronoBox
The ChronoBox class provides a convenient and powerful API for date manipulation, formatting, and validation.
### Constructor
```typescript
new ChronoBox(date?: DateInput, format?: TFormat)
```
- date (optional): The date to initialize the ChronoBox instance. If not provided, the current date and time will be used.
- format (optional): The format for the date output. Defaults to DateFormat.ISO.
### Methods
```typescript
add(amount: number, unit: T): ChronoBox
```
Adds a specified amount of time to the current date.
- amount: The amount of time to add.
- unit: The unit of time to add (e.g., TimeUnit.DAYS, TimeUnit.MONTHS, etc.).
- returns: A new ChronoBox instance with the updated date.
---
```typescript
subtract(amount: number, unit: T): ChronoBox
```
Subtracts a specified amount of time from the current date.
- amount: The amount of time to subtract.
- unit: The unit of time to subtract.
- returns: A new ChronoBox instance with the updated date.
---
```typescript
diff(other: DateInput, unit: TimeUnit = TimeUnit.DAYS): number
```
Calculates the difference between the current date and another date in the specified time unit.
- other: The other date to compare with.
- unit: The unit of time for the difference (e.g., TimeUnit.DAYS, TimeUnit.MONTHS, etc.).
- returns: The difference in the specified time unit.
---
```typescript
getComponents(): DateComponents
```
Returns the individual components (year, month, day, hours, minutes, seconds, milliseconds) of the date.
- returns: An object with the above structure.
---
```typescript
formatDate(): string
```
Formats the current date according to the specified format.
- returns: A string representation of the date based on the format.
---
```typescript
isValid(): boolean
```
Checks whether the current date is valid.
- returns: true if the date is valid, otherwise false.
---
```typescript
toDate(): Date
```
Returns the underlying Date object from the ChronoBox instance.
- returns: A Date object representing the current date.
---
```typescript
withFormat(newFormat: NewFormat): ChronoBox
```
Creates a new ChronoBox instance with a different format.
- newFormat: The new format for the date.
- returns: A new ChronoBox instance with the updated format.
---
```typescript
isAfter(other: DateInput, granularity: TimeUnit = TimeUnit.MILLISECONDS): boolean
```
Checks if this date is after the specified date.
- other: The date to compare against.
- granularity: The time unit granularity for comparison (defaults to milliseconds for exact comparison).
- returns: true if this date is after the specified date.
---
```typescript
isBefore(other: DateInput, granularity: TimeUnit = TimeUnit.MILLISECONDS): boolean
```
Checks if this date is before the specified date.
- other: The date to compare against.
- granularity: The time unit granularity for comparison (defaults to milliseconds for exact comparison).
- returns: true if this date is before the specified date.
---
```typescript
convertTimezone(date: Date | ChronoBox, fromTimezone: string, toTimezone: string): Date
```
Converts a date from one timezone to another
- date: The date to convert.
- fromTimezone: The source timezone (e.g., 'America/New_York').
- toTimezone: The target timezone (e.g., 'Europe/London').
- returns: A new Date object representing the same moment in the target timezone.
---
```typescript
getTimezoneOffsetMinutes(date: Date | ChronoBox, timezone: string): number
```
Gets the timezone offset in minutes for a date in a specific timezone.
- date: The date to get the offset for.
- timezone: The timezone to get the offset for (e.g., 'America/New_York').
- returns: The timezone offset in minutes (positive for timezones behind UTC, negative for timezones ahead of UTC).
---
```typescript
isInDST(date: Date | ChronoBox, timezone: string): boolean
```
Checks if a date is in Daylight Saving Time (DST) for a specific timezone.
- date: The date to check.
- timezone: The timezone to check for DST (e.g., 'America/New_York').
- returns: true if the date is in DST for the specified timezone, false otherwise.
---
```typescript
findDSTTransitions(year: number, timezone: string): { start: Date | null; end: Date | null }
```
Finds the exact DST transition times for a given year in a specific timezone.
- year: The year to find DST transitions for.
- timezone: The timezone to check (e.g., 'America/New_York').
- returns: An object with start and end properties containing the DST transition dates, or null if no DST.
---
```typescript
startOf(unit: T): ChronoBox
```
Gets the start of a specified time unit for the current date.
- unit: The time unit to get the start of (e.g., day, hour, minute).
- Returns: A new ChronoBox instance set to the start of the specified unit.
---
```typescript
endOf(unit: T): ChronoBox
```
Gets the end of a specified time unit for the current date.
- unit: The time unit to get the end of (e.g., day, hour, minute).
- Returns: A new ChronoBox instance set to the end of the specified unit.
---
```typescript
fromNow(referenceDate?: DateInput): string
```
Gets a human-readable string representing the time difference between the current date and now.
- referenceDate?: An optional date to compare against. Defaults to the current time.
- Returns: A string representing the relative time difference, e.g., "5 minutes ago", "in 2 days".
## 📄 License
ChronoBox is open-source software, licensed under the [MIT License](LICENSE).
## ❤️ Support
If you find ChronoBox helpful, please give it a ⭐️ on GitHub and share it with your fellow developers!