lune/types/DateTime.luau

export type Locale = "en" | "de" | "es" | "fr" | "it" | "ja" | "pl" | "pt-br" | "pt" | "tr"

export type DateTimeValues = {
	--- Year(s), in the range 1400 -> 9999
	year: number,
	--- Month(s), in the range 1 -> 12
	month: number,
	--- Day(s), in the range 1 -> 31
	day: number,
	--- Hour(s), in the range 0 -> 23
	hour: number,
	--- Minute(s), in the range 0 -> 59
	minute: number,
	--- Second(s), in the range 0 -> 60, where 60 is a leap second
	second: number,
	--- Millisecond(s), in the range 0 -> 999
	millisecond: number?,
}

local DateTime = {
	--- Number of seconds passed since the UNIX epoch.
	unixTimestamp = 0,
	--- Number of milliseconds passed since the UNIX epoch.
	unixTimestampMillis = 0,
}

--[=[
	@within DateTime

	Formats this `DateTime` as an ISO 8601 date-time string.

	Some examples of ISO 8601 date-time strings:

	- `2020-02-22T18:12:08Z`
	- `2000-01-31T12:34:56+05:00`
	- `1970-01-01T00:00:00.055Z`

	@return string -- The ISO 8601 formatted string
]=]
function DateTime.toIsoDate(self: DateTime): string
	return nil :: any
end

--[=[
	@within DateTime

	Extracts local time values from this `DateTime`.

	The returned table contains the following values:

	| Key           | Type     | Range          |
	|---------------|----------|----------------|
	| `year`        | `number` | `1400 -> 9999` |
	| `month`       | `number` | `1 -> 12`      |
	| `day`         | `number` | `1 -> 31`      |
	| `hour`        | `number` | `0 -> 23`      |
	| `minute`      | `number` | `0 -> 59`      |
	| `second`      | `number` | `0 -> 60`      |
	| `millisecond` | `number` | `0 -> 999`     |

	@return DateTimeValues -- A table of DateTime values
]=]
function DateTime.toLocalTime(self: DateTime): DateTimeValues
	return nil :: any
end

--[=[
	@within DateTime

	Extracts UTC (universal) time values from this `DateTime`.

	The returned table contains the following values:

	| Key           | Type     | Range          |
	|---------------|----------|----------------|
	| `year`        | `number` | `1400 -> 9999` |
	| `month`       | `number` | `1 -> 12`      |
	| `day`         | `number` | `1 -> 31`      |
	| `hour`        | `number` | `0 -> 23`      |
	| `minute`      | `number` | `0 -> 59`      |
	| `second`      | `number` | `0 -> 60`      |
	| `millisecond` | `number` | `0 -> 999`     |

	@return DateTimeValues -- A table of DateTime values
]=]
function DateTime.toUniversalTime(self: DateTime): DateTimeValues
	return nil :: any
end

--[=[
	@within DateTime

	Formats this `DateTime` using the given `formatString` and `locale`, as local time.

	The given `formatString` is parsed using a `strftime`/`strptime`-inspired
	date and time formatting syntax, allowing tokens such as the following:

	| Token | Example  | Description   |
	|-------|----------|---------------|
	| `%Y`  | `1998`   | Year number   |
	| `%m`  | `04`     | Month number  |
	| `%d`  | `29`     | Day number    |
	| `%A`  | `Monday` | Weekday name  |
	| `%M`  | `59`     | Minute number |
	| `%S`  | `10`     | Second number |

	For a full reference of all available tokens, see the
	[chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).

	If not provided, `formatString` and `locale` will default
	to `"%Y-%m-%d %H:%M:%S"` and `"en"` (english) respectively.

	@param formatString -- A string containing formatting tokens
	@param locale -- The locale the time should be formatted in
	@return string -- The formatting string
]=]
function DateTime.formatLocalTime(self: DateTime, formatString: string?, locale: Locale?): string
	return nil :: any
end

--[=[
	@within DateTime

	Formats this `DateTime` using the given `formatString` and `locale`, as UTC (universal) time.

	The given `formatString` is parsed using a `strftime`/`strptime`-inspired
	date and time formatting syntax, allowing tokens such as the following:

	| Token | Example  | Description   |
	|-------|----------|---------------|
	| `%Y`  | `1998`   | Year number   |
	| `%m`  | `04`     | Month number  |
	| `%d`  | `29`     | Day number    |
	| `%A`  | `Monday` | Weekday name  |
	| `%M`  | `59`     | Minute number |
	| `%S`  | `10`     | Second number |

	For a full reference of all available tokens, see the
	[chrono documentation](https://docs.rs/chrono/latest/chrono/format/strftime/index.html).

	If not provided, `formatString` and `locale` will default
	to `"%Y-%m-%d %H:%M:%S"` and `"en"` (english) respectively.

	@param formatString -- A string containing formatting tokens
	@param locale -- The locale the time should be formatted in
	@return string -- The formatting string
]=]
function DateTime.formatUniversalTime(
	self: DateTime,
	formatString: string?,
	locale: Locale?
): string
	return nil :: any
end

export type DateTime = typeof(DateTime)

--[=[
	@class DateTime

	Built-in library for date & time

	### Example usage

	```lua
	local DateTime = require("@lune/datetime")

	-- Creates a DateTime for the current exact moment in time
	local now = DateTime.now()

	-- Formats the current moment in time as an ISO 8601 string
	print(now:toIsoDate())

	-- Formats the current moment in time, using the local
	-- time, the Frech locale, and the specified time string
	print(now:formatLocalTime("%A, %d %B %Y", "fr"))

	-- Returns a specific moment in time as a DateTime instance
	local someDayInTheFuture = DateTime.fromLocalTime({
		year = 3033,
		month = 8,
		day = 26,
		hour = 16,
		minute = 56,
		second = 28,
		millisecond = 892,
	})

	-- Extracts the current local date & time as separate values (same values as above table)
	print(now:toLocalTime())

	-- Returns a DateTime instance from a given float, where the whole
	-- denotes the seconds and the fraction denotes the milliseconds
	-- Note that the fraction for millis here is completely optional
	DateTime.fromUnixTimestamp(871978212313.321)

	-- Extracts the current universal (UTC) date & time as separate values
	print(now:toUniversalTime())
	```
]=]
local dateTime = {}

--[=[
	@within DateTime

	Returns a `DateTime` representing the current moment in time.

	@return DateTime -- The new DateTime object
]=]
function dateTime.now(): DateTime
	return nil :: any
end

--[=[
	@within DateTime

	Creates a new `DateTime` from the given UNIX timestamp.

	This timestamp may contain both a whole and fractional part -
	where the fractional part denotes milliseconds / nanoseconds.

	Example usage of fractions:

	- `DateTime.fromUnixTimestamp(123456789.001)` - one millisecond
	- `DateTime.fromUnixTimestamp(123456789.000000001)` - one nanosecond

	Note that the fractional part has limited precision down to exactly
	one nanosecond, any fraction that is more precise will get truncated.

	@param unixTimestamp -- Seconds passed since the UNIX epoch
	@return DateTime -- The new DateTime object
]=]
function dateTime.fromUnixTimestamp(unixTimestamp: number): DateTime
	return nil :: any
end

--[=[
	@within DateTime

	Creates a new `DateTime` from the given date & time values table, in universal (UTC) time.

	The given table must contains the following values:

	| Key      | Type     | Range          |
	|----------|----------|----------------|
	| `year`   | `number` | `1400 -> 9999` |
	| `month`  | `number` | `1 -> 12`      |
	| `day`    | `number` | `1 -> 31`      |
	| `hour`   | `number` | `0 -> 23`      |
	| `minute` | `number` | `0 -> 59`      |
	| `second` | `number` | `0 -> 60`      |

	An additional `millisecond` value may also be included,
	and should be within the range `0 -> 999`, but is optional.

	This constructor is fallible and may throw an error in the following situations:

	- Date units (year, month, day) that produce an invalid date will raise an error. For example, January 32nd or February 29th on a non-leap year.
	- Non-integer values are rounded down. For example, providing 2.5 hours is equivalent to providing 2 hours, not 2 hours and 30 minutes.

	@param values -- Table containing date & time values
	@return DateTime -- The new DateTime object
]=]
function dateTime.fromUniversalTime(values: DateTimeValues): DateTime
	return nil :: any
end

--[=[
	@within DateTime

	Creates a new `DateTime` from the given date & time values table, in local time.

	The given table must contains the following values:

	| Key      | Type     | Range          |
	|----------|----------|----------------|
	| `year`   | `number` | `1400 -> 9999` |
	| `month`  | `number` | `1 -> 12`      |
	| `day`    | `number` | `1 -> 31`      |
	| `hour`   | `number` | `0 -> 23`      |
	| `minute` | `number` | `0 -> 59`      |
	| `second` | `number` | `0 -> 60`      |

	An additional `millisecond` value may also be included,
	and should be within the range `0 -> 999`, but is optional.

	This constructor is fallible and may throw an error in the following situations:

	- Date units (year, month, day) that produce an invalid date will raise an error. For example, January 32nd or February 29th on a non-leap year.
	- Non-integer values are rounded down. For example, providing 2.5 hours is equivalent to providing 2 hours, not 2 hours and 30 minutes.

	@param values -- Table containing date & time values
	@return DateTime -- The new DateTime object
]=]
function dateTime.fromLocalTime(values: DateTimeValues): DateTime
	return nil :: any
end

--[=[
	@within DateTime

	Creates a new `DateTime` from an ISO 8601 date-time string.

	This constructor is fallible and may throw an error if the given
	string does not strictly follow the ISO 8601 date-time string format.

	Some examples of valid ISO 8601 date-time strings:

	- `2020-02-22T18:12:08Z`
	- `2000-01-31T12:34:56+05:00`
	- `1970-01-01T00:00:00.055Z`

	@param isoDate -- An ISO 8601 formatted string
	@return DateTime -- The new DateTime object
]=]
function dateTime.fromIsoDate(isoDate: string): DateTime
	return nil :: any
end

return dateTime