diff --git a/types/DateTime.luau b/types/DateTime.luau index 016fd7a..1a6344c 100644 --- a/types/DateTime.luau +++ b/types/DateTime.luau @@ -1,94 +1,102 @@ -export type Locale = "en" | "de" | "es" | "fr" | "it" | "ja" | "pl" | "pt-br" | "pt" | "tr" +--[[ + NOTE: We export a couple different DateTimeValues types below to ensure + that types are completely accurate, for method args milliseconds will + always be optional, but for return values millis are always included -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 + If we figure out some better strategy here where we can + export just a single type while maintaining accuracy we + can change to that in a future breaking semver release +]] + +type OptionalMillisecond = { millisecond: number?, } +type Millisecond = { + millisecond: number, +} + +--[=[ + @interface Locale + @within DateTime + + Enum type representing supported DateTime locales. + + Currently supported locales are: + + - `en` - English + - `de` - German + - `es` - Spanish + - `fr` - French + - `it` - Italian + - `ja` - Japanese + - `pl` - Polish + - `pt-br` - Brazilian Portuguese + - `pt` - Portuguese + - `tr` - Turkish +]=] +export type Locale = "en" | "de" | "es" | "fr" | "it" | "ja" | "pl" | "pt-br" | "pt" | "tr" + +--[=[ + @interface DateTimeValues + @within DateTime + + Individual date & time values, representing the primitives that make up a `DateTime`. + + This is a dictionary that will contain the following values: + + - `year` - Year(s), in the range 1400 -> 9999 + - `month` - Month(s), in the range 1 -> 12 + - `day` - Day(s), in the range 1 -> 31 + - `hour` - Hour(s), in the range 0 -> 23 + - `minute` - Minute(s), in the range 0 -> 59 + - `second` - Second(s), in the range 0 -> 60, where 60 is a leap second + + An additional `millisecond` value may also be included, + and should be within the range `0 -> 999`, but is optional. + + However, any method returning this type should be guaranteed + to include milliseconds - see individual methods to verify. +]=] +export type DateTimeValues = { + year: number, + month: number, + day: number, + hour: number, + minute: number, + second: number, +} + +--[=[ + @interface DateTimeValueArguments + @within DateTime + + Alias for `DateTimeValues` with an optional `millisecond` value. + + Refer to the `DateTimeValues` documentation for additional information. +]=] +export type DateTimeValueArguments = DateTimeValues & OptionalMillisecond + +--[=[ + @interface DateTimeValueReturns + @within DateTime + + Alias for `DateTimeValues` with a mandatory `millisecond` value. + + Refer to the `DateTimeValues` documentation for additional information. +]=] +export type DateTimeValueReturns = DateTimeValues & Millisecond + local DateTime = { --- Number of seconds passed since the UNIX epoch. - unixTimestamp = 0, + unixTimestamp = (nil :: any) :: number, --- Number of milliseconds passed since the UNIX epoch. - unixTimestampMillis = 0, + unixTimestampMillis = (nil :: any) :: number, } --[=[ @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 + @tag Method Formats this `DateTime` using the given `formatString` and `locale`, as local time. @@ -120,6 +128,7 @@ end --[=[ @within DateTime + @tag Method Formats this `DateTime` using the given `formatString` and `locale`, as UTC (universal) time. @@ -153,6 +162,72 @@ function DateTime.formatUniversalTime( return nil :: any end +--[=[ + @within DateTime + @tag Method + + Formats this `DateTime` as an ISO 8601 date-time string. + + Some examples of ISO 8601 date-time strings are: + + - `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 + @tag Method + + Extracts separated local date & 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 DateTimeValueReturns -- A table of DateTime values +]=] +function DateTime.toLocalTime(self: DateTime): DateTimeValueReturns + return nil :: any +end + +--[=[ + @within DateTime + @tag Method + + Extracts separated UTC (universal) date & 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 DateTimeValueReturns -- A table of DateTime values +]=] +function DateTime.toUniversalTime(self: DateTime): DateTimeValueReturns + return nil :: any +end + export type DateTime = typeof(DateTime) --[=[ @@ -202,6 +277,7 @@ local dateTime = {} --[=[ @within DateTime + @tag Constructor Returns a `DateTime` representing the current moment in time. @@ -213,6 +289,7 @@ end --[=[ @within DateTime + @tag Constructor Creates a new `DateTime` from the given UNIX timestamp. @@ -236,10 +313,11 @@ end --[=[ @within DateTime + @tag Constructor Creates a new `DateTime` from the given date & time values table, in universal (UTC) time. - The given table must contains the following values: + The given table must contain the following values: | Key | Type | Range | |----------|----------|----------------| @@ -253,24 +331,28 @@ end An additional `millisecond` value may also be included, and should be within the range `0 -> 999`, but is optional. + Any non-integer values in the given table will be rounded down. + + ### Errors + 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. + - Date units (year, month, day) were given that produce an invalid date. For example, January 32nd or February 29th on a non-leap year. @param values -- Table containing date & time values @return DateTime -- The new DateTime object ]=] -function dateTime.fromUniversalTime(values: DateTimeValues): DateTime +function dateTime.fromUniversalTime(values: DateTimeValueArguments): DateTime return nil :: any end --[=[ @within DateTime + @tag Constructor Creates a new `DateTime` from the given date & time values table, in local time. - The given table must contains the following values: + The given table must contain the following values: | Key | Type | Range | |----------|----------|----------------| @@ -284,27 +366,33 @@ end An additional `millisecond` value may also be included, and should be within the range `0 -> 999`, but is optional. + Any non-integer values in the given table will be rounded down. + + ### Errors + 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. + - Date units (year, month, day) were given that produce an invalid date. For example, January 32nd or February 29th on a non-leap year. @param values -- Table containing date & time values @return DateTime -- The new DateTime object ]=] -function dateTime.fromLocalTime(values: DateTimeValues): DateTime +function dateTime.fromLocalTime(values: DateTimeValueArguments): DateTime return nil :: any end --[=[ @within DateTime + @tag Constructor Creates a new `DateTime` from an ISO 8601 date-time string. + ### Errors + 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: + Some examples of valid ISO 8601 date-time strings are: - `2020-02-22T18:12:08Z` - `2000-01-31T12:34:56+05:00`