io.github.edadma.datefns

The io.github.edadma.datefns library provides utilities for working with dates in Scala.js projects.

This library is inspired by the JavaScript date-fns library and provides similar functionality in a Scala-friendly way. It wraps JavaScript's Date objects with an opaque type and provides extension methods and utility functions to make working with dates more convenient.

==Overview==

The library is organized into several categories of functions:

'''Date creation''': Functions to create Date objects (now, parseISO, fromUnixTime, newDate)
'''Formatting''': Functions to format dates into strings (format, formatISO)
'''Comparison''': Functions to compare dates (isAfter, isBefore, isEqual, isSameDay, etc.)
'''Manipulation''': Functions to modify dates (addDays, subMonths, startOfDay, endOfMonth, etc.)

==Usage Examples==

Creating a date:

import io.github.edadma.datefns.*

// Current date and time
val today = now

// Create a specific date
val christmas = newDate(2023, 11, 25) // December 25, 2023

// Parse an ISO date string
val dateFromString = parseISO("2023-12-25T12:00:00.000Z")

Formatting dates:

import io.github.edadma.datefns.*

val date = newDate(2023, 11, 25, 14, 30)

// Custom format
format(date, "MMMM d, yyyy 'at' h:mm a") // "December 25, 2023 at 2:30 PM"

// ISO format
formatISO(date) // "2023-12-25T14:30:00.000Z"

Comparing dates:

import io.github.edadma.datefns.*

val date1 = newDate(2023, 0, 1)  // January 1, 2023
val date2 = newDate(2023, 11, 31) // December 31, 2023

isBefore(date1, date2) // true
isSameYear(date1, date2) // true
isSameMonth(date1, date2) // false

Manipulating dates:

import io.github.edadma.datefns.*

val date = newDate(2023, 11, 25)

val nextWeek = addDays(date, 7)
val previousMonth = subMonths(date, 1)
val startOfMonthDate = startOfMonth(date)

==Note on Month Indexing==

Following JavaScript's Date convention, months are represented as 0-based indices: 0 = January, 1 = February, ..., 11 = December.

Attributes

See also: GitHub Repository

Members list

Type members

Classlikes

Represents a time interval between two dates.

An interval is defined by a start date and an end date. It includes all the time from the start date up to and including the end date. For most operations, it's expected that the start date is chronologically before or equal to the end date.

Intervals are useful for:

Checking if a date falls within a specific time range
Processing a range of dates between two boundaries
Computing the duration between two dates
Finding overlaps between different date ranges

Value parameters

end: The ending date of the interval (inclusive)
start: The starting date of the interval (inclusive)

Attributes

Example

 // Create an interval for the year 2023 val year2023 = Interval( newDate(2023, 0, 1), // January 1, 2023
 newDate(2023, 11, 31) // December 31, 2023 )
// Create a week interval val weekInterval = Interval( newDate(2023, 5, 12), // June 12, 2023 newDate(2023, 5,
18) // June 18, 2023 )
// Create an interval between now and a week from now val currentWeek = Interval( now, addDays(now, 7) )

Supertypes

trait Serializable

trait Product

trait Equals

class Object

trait Matchable

class Any

Show all

Types

A wrapper for JavaScript's Date object in a Scala.js environment.

This opaque type encapsulates a JavaScript Date instance with type-safe Scala methods. The wrapper provides Scala-friendly access to the underlying JavaScript Date functionality while maintaining proper type signatures.

Attributes

See also

JavaScript Date documentation

Example

 // Create a new date representing the current moment
 val currentDate = now
 // Access date components
 val currentYear = currentDate.getFullYear
 val currentMonth = currentDate.getMonth  // 0-11, January is 0
 val currentDay = currentDate.getDate     // Day of month (1-31)

Value members

Concrete methods

Adds the specified number of days to the given date.

Value parameters

amount: The amount of days to be added (can be negative)
date: The date to be changed

Attributes

Returns

A new date with the days added

Example

val date = newDate(2023, 11, 25) // December 25, 2023 val newDate = addDays(date, 7) // January 1, 2024

Adds the specified number of months to the given date. If the original date's day exceeds the number of days in the target month, the result will be adjusted to the last day of the target month.

Value parameters

amount: The amount of months to be added (can be negative)
date: The date to be changed

Attributes

Returns

A new date with the months added

Example

 // When the target month has fewer days than the original date's day:
 val date = newDate(2023, 0, 31) // January 31, 2023
 val newDate = addMonths(date, 1) // February 28, 2023 (adjusted to last day of Feb 2023)
 // When using a leap year:
 val leapDate = newDate(2020, 0, 31) // January 31, 2020 (leap year)
 val leapResult = addMonths(leapDate, 1) // February 29, 2020 (adjusted to last day of Feb 2020)
 // When the day exists in the target month:
 val marchDate = newDate(2023, 2, 15) // March 15, 2023
 val juneDate = addMonths(marchDate, 3) // June 15, 2023

Adds the specified number of years to the given date. Takes leap years into account; if the original date is February 29 and the new year is not a leap year, the result will be February 28.

Value parameters

amount: The amount of years to be added (can be negative)
date: The date to be changed

Attributes

Returns

A new date with the years added

Example

 val date = newDate(2020, 1, 29) // February 29, 2020 (leap year) val newDate = addYears(date, 1) //
 February 28, 2021 (not leap year)
val regularDate = newDate(2023, 5, 15) // June 15, 2023 val futureDate = addYears(regularDate, 5) // June 15,
2028

Returns a new date representing the end of a day (23:59:59.999) for the given date.

Value parameters

date: The date to be changed

Attributes

Returns

A new date with time set to the end of the day

Example

 val date = newDate(2023, 11, 25, 14, 30, 45) // December 25, 2023, 14:30:45 val dayEnd = endOfDay(date) //
 December 25, 2023, 23:59:59.999

Returns a new date representing the end of a month (last day, 23:59:59.999) for the given date.

Value parameters

date: The date to be changed

Attributes

Returns

A new date set to the end of the month

Example

 val date = newDate(2023, 11, 15, 14, 30, 45) // December 15, 2023, 14:30:45 val monthEnd = endOfMonth(date)
 // December 31, 2023, 23:59:59.999
val febDate = newDate(2024, 1, 15) // February 15, 2024 (leap year) val febEnd = endOfMonth(febDate) // February
29, 2024, 23:59:59.999

Formats a date according to the specified format string.

Supported format tokens:

Year: 'yyyy' (4-digit year), 'yy' (2-digit year)
Month: 'MMMM' (full month name), 'MMM' (3-letter month name), 'MM' (2-digit month), 'M' (month number)
Day: 'dd' (2-digit day), 'd' (day number)
Day of week: 'EEEE' (full day name), 'EEE' (3-letter day name), 'E' (day of week number, 0-6)
Hours: 'HH' (2-digit 24-hour), 'H' (24-hour), 'hh' (2-digit 12-hour), 'h' (12-hour)
Minutes: 'mm' (2-digit), 'm' (minutes)
Seconds: 'ss' (2-digit), 's' (seconds)
Milliseconds: 'SSS' (3-digit milliseconds)
AM/PM: 'a'

Text can be escaped using single quotes: 'text'

Value parameters

date: The date to format
formatStr: The format string with tokens to be replaced with date values

Attributes

Returns: The formatted date string

Formats a date according to the ISO 8601 standard.

The format is: YYYY-MM-DDTHH:mm:ss.sssZ Where Z is the time zone offset (UTC indicated by 'Z').

Value parameters

date: The date to format

Attributes

Returns

The ISO 8601 formatted date string

Example

 val date = newDate(2023, 11, 25, 14, 30, 45, 123) formatISO(date) // "2023-12-25T14:30:45.123Z" (or with
 timezone offset)

Creates a Date from a Unix timestamp (seconds since January 1, 1970, 00:00:00 UTC).

Value parameters

timestamp: The number of seconds since the Unix epoch

Attributes

Returns

A new Date object representing the timestamp

Example

val date = fromUnixTime(1640430000) // December 25, 2021 at 09:46:40 UTC

Checks if the first date is after the second date.

Value parameters

date: The date to check
dateToCompare: The date to compare against

Attributes

Returns

True if the first date is after the second date, false otherwise

Example

 val date1 = newDate(2023, 11, 25) // December 25, 2023 val date2 = newDate(2023, 0, 1) // January 1,
 2023
isAfter(date1, date2) // true isAfter(date2, date1) // false

Checks if the first date is before the second date.

Value parameters

date: The date to check
dateToCompare: The date to compare against

Attributes

Returns

True if the first date is before the second date, false otherwise

Example

 val date1 = newDate(2023, 0, 1) // January 1, 2023 val date2 = newDate(2023, 11, 25) // December 25,
 2023
isBefore(date1, date2) // true isBefore(date2, date1) // false

Checks if two dates are equal to each other. Dates are considered equal if they represent the same millisecond timestamp.

Value parameters

date1: The first date to compare
date2: The second date to compare

Attributes

Returns

True if the dates are equal, false otherwise

Example

 val date1 = newDate(2023, 11, 25, 12, 0, 0) val date2 = newDate(2023, 11, 25, 12, 0, 0) val date3 =
 newDate(2023, 11, 25, 12, 0, 1)
isEqual(date1, date2) // true isEqual(date1, date3) // false

Checks if the given date is in the future compared to current time.

Value parameters

date: The date to check

Attributes

Returns

True if the date is in the future, false otherwise

Example

 val futureDate = addYears(now, 1) // One year from now
isFuture(futureDate) // true isFuture(now) // false

Checks if the given date is in the past compared to current time.

Value parameters

date: The date to check

Attributes

Returns

True if the date is in the past, false otherwise

Example

 val pastDate = subYears(now, 1) // One year ago
isPast(pastDate) // true isPast(now) // false

Checks if two dates fall on the same day (ignoring time parts).

Value parameters

date1: The first date to check
date2: The second date to check

Attributes

Returns

True if the dates are on the same day, false otherwise

Example

 val date1 = newDate(2023, 11, 25, 12, 0, 0) val date2 = newDate(2023, 11, 25, 18, 30, 0) val date3 =
 newDate(2023, 11, 26, 12, 0, 0)
isSameDay(date1, date2) // true isSameDay(date1, date3) // false

Checks if two dates fall within the same month and year.

Value parameters

dateLeft: The first date to check
dateRight: The second date to check

Attributes

Returns

True if the dates are in the same month and year, false otherwise

Example

 val date1 = newDate(2023, 11, 1) // December 1, 2023 val date2 = newDate(2023, 11, 25) // December 25,
 2023 val date3 = newDate(2023, 10, 1) // November 1, 2023
isSameMonth(date1, date2) // true isSameMonth(date1, date3) // false

Checks if two dates fall within the same year.

Value parameters

dateLeft: The first date to check
dateRight: The second date to check

Attributes

Returns

True if the dates are in the same year, false otherwise

Example

 val date1 = newDate(2023, 0, 1) // January 1, 2023 val date2 = newDate(2023, 11, 31) // December 31,
 2023 val date3 = newDate(2024, 0, 1) // January 1, 2024
isSameYear(date1, date2) // true isSameYear(date1, date3) // false

Checks if the given date is today in the local time zone.

Value parameters

date: The date to check

Attributes

Returns

True if the given date is today, false otherwise

Example

 val someDate = newDate(2023, 6, 15) // July 15, 2023 isToday(someDate) // false (unless today happens to be
 July 15, 2023)
isToday(now) // always true

Checks if the given date falls on a weekend (Saturday or Sunday).

Value parameters

date: The date to check

Attributes

Returns

True if the date is a weekend day, false otherwise

Example

 val saturday = newDate(2023, 11, 23) // December 23, 2023 (a Saturday) val monday = newDate(2023, 11,
 25) // December 25, 2023 (a Monday)
isWeekend(saturday) // true isWeekend(monday) // false

Checks if the date is within the given time interval. The interval boundaries are inclusive (>=start, <=end).

Value parameters

date: The date to check
interval: The interval to check against, with start and end dates

Attributes

Returns

True if the date is within the interval, false otherwise

Example

 val start = newDate(2023, 0, 1) // January 1, 2023 val end = newDate(2023, 11, 31) // December 31, 2023
 val interval = Interval(start, end)
val dateToCheck = createDate(2023, 6, 15) // July 15, 2023 val dateOutside = createDate(2024, 0, 1) // January 1,
2024
isWithinInterval(dateToCheck, interval) // true isWithinInterval(dateOutside, interval) // false
isWithinInterval(start, interval) // true (inclusive) isWithinInterval(end, interval) // true (inclusive)

Creates a date from year, month, day, and time components.

Value parameters

day: The day of the month (1-31)
hours: The hour (0-23)
milliseconds: The milliseconds (0-999)
minutes: The minutes (0-59)
month: The month index (0-11, where 0 is January and 11 is December)
seconds: The seconds (0-59)
year: The full year (e.g., 2023)

Attributes

Returns

A new Date object

Example

val christmasEve = newDate(2023, 11, 24, 20, 0, 0) // December 24, 2023 at 8:00:00 PM

Creates a new Date object representing the current moment in time.

Attributes

Returns

A Date object representing the current date and time

Example

 val currentDate = now
 println(s"Current time: ${currentDate.toISOString}")

Parses an ISO 8601 formatted date string (such as 2023-12-25T14:30:45.123Z) into a Date object.

This function relies on the JavaScript Date constructor's ability to parse ISO 8601 strings.

Value parameters

dateString: ISO 8601 formatted date string to parse

Attributes

Returns

A new Date object representing the parsed date

Example

val date = parseISO("2023-12-25T14:30:45.123Z") // December 25, 2023 at 14:30:45.123

Returns a new date representing the start of a day (00:00:00.000) for the given date.

Value parameters

date: The date to be changed

Attributes

Returns

A new date with time set to the start of the day

Example

 val date = newDate(2023, 11, 25, 14, 30, 45) // December 25, 2023, 14:30:45 val dayStart = startOfDay(date)
 // December 25, 2023, 00:00:00.000

Returns a new date representing the start of a month (1st day, 00:00:00.000) for the given date.

Value parameters

date: The date to be changed

Attributes

Returns

A new date set to the start of the month

Example

 val date = newDate(2023, 11, 25, 14, 30, 45) // December 25, 2023, 14:30:45 val monthStart =
 startOfMonth(date) // December 1, 2023, 00:00:00.000

Subtracts the specified number of days from the given date. This is a convenience function that calls addDays with a negative amount.

Value parameters

amount: The amount of days to be subtracted
date: The date to be changed

Attributes

Returns

A new date with the days subtracted

See also

addDays

Example

val date = newDate(2023, 0, 1) // January 1, 2023 val newDate = subDays(date, 7) // December 25, 2022

Subtracts the specified number of months from the given date. This is a convenience function that calls addMonths with a negative amount.

Value parameters

amount: The amount of months to be subtracted
date: The date to be changed

Attributes

Returns

A new date with the months subtracted

See also

addMonths

Example

val date = newDate(2023, 2, 15) // March 15, 2023 val newDate = subMonths(date, 3) // December 15, 2022

Subtracts the specified number of years from the given date. This is a convenience function that calls addYears with a negative amount.

Value parameters

amount: The amount of years to be subtracted
date: The date to be changed

Attributes

Returns

A new date with the years subtracted

See also

addYears

Example

val date = newDate(2023, 5, 15) // June 15, 2023 val newDate = subYears(date, 3) // June 15, 2020

Extensions

extension (d: Date)

Returns the day of the month (1-31) for this date according to local time.

Attributes

Returns

The day of the month (1-31)

Example

 val date = now
 val dayOfMonth = date.getDate  // For example: 15

Returns the day of the week (0-6) for this date according to local time.

Attributes

Returns

The day of the week (0-6)

Note

Day numbering starts at 0 for Sunday through 6 for Saturday.

Example

 val date = now
 val dayOfWeek = date.getDay  // 0 for Sunday, 6 for Saturday

Returns the year (4 digits) for this date according to local time.

Attributes

Returns

The 4-digit year

Example

 val date = now
 val year = date.getFullYear  // For example: 2024

Returns the hour (0-23) for this date according to local time.

Attributes

Returns

The hour (0-23)

Example

 val date = now
 val hour = date.getHours  // For example: 14

Returns the milliseconds (0-999) for this date according to local time.

Attributes

Returns

The milliseconds (0-999)

Example

 val date = now
 val milliseconds = date.getMilliseconds  // For example: 34

Returns the minutes (0-59) for this date according to local time.

Attributes

Returns

The minutes (0-59)

Example

 val date = now
 val minutes = date.getMinutes  // For example: 35

Returns the month (0-11) for this date according to local time.

Attributes

Returns

The month (0-11)

Note

Month numbering starts at 0 for January through 11 for December.

Example

 val date = now
 val month = date.getMonth  // 0 for January, 11 for December

Returns the seconds (0-59) for this date according to local time.

Attributes

Returns

The seconds (0-59)

Example

 val date = now
 val seconds = date.getSeconds  // For example: 29

Returns the number of milliseconds since January 1, 1970, 00:00:00 UTC.

Attributes

Returns

The timestamp in milliseconds

Example

 val date = now
 val timestamp = date.getTime  // For example: 1715433729034

Determines if this date is valid.

Attributes

Returns

true if the date is valid, false otherwise

Example

 val validDate = now
 val invalidDate = new js.Date("invalid date").asInstanceOf[Date]
 validDate.isValid   // true
 invalidDate.isValid // false

Returns this date as an ISO 8601 formatted string.

The format is: YYYY-MM-DDTHH:mm:ss.sssZ

Attributes

Returns

The date formatted according to ISO 8601

Example

 val date = now
 val isoString = date.toISOString  // For example: "2024-05-11T14:35:29.034Z"

In this article

Generated with