$time / %24time

Namespace: $time

This namespace provides features for date/time. Mainly, there are utilities using Date class and feature Date.prototype.toLocaleString.

version 1.5.0

see https://github.com/jaandrle/dollar_time

Public Namespaces

Date_utils

Interfaces

Type aliases

Public Variables

_
formats

Public Functions

Private Functions

getFormatObject

Type aliases

ArrayOfOperation

Ƭ Private ArrayOfOperation<O>: [O, O extends keyof Intl.DateTimeFormatOptions ? Intl.DateTimeFormatOptions[O] : string, undefined | "ordinal_number" | "two_letters"]

First two items represents key/value of Date.prototype.toLocaleString (i. e. "weekday", "month") or "text". Last item reprezents internal manipulations:
- "ordinal_number": Include suffix – only English supported
- "two_letters": 1→01, …

Type parameters

Name	Type
`O`	extends `OperationTypes`

ArrayOfOperations

Ƭ Private ArrayOfOperations: ArrayOfOperation<OperationTypes>[]

DateArray

Ƭ Private DateArray: [string, string, keyof ary_ianna_time_offsets | keyof ary_ianna_time_offsets_keyed | ""]

Array<string> reprezentation of date/time:

[
  date: is always in form of "YYYY-MM-DD" or "",
  time: is always in form of "HH:mm:SS" or "HH:mm:00" or "",
  zone: is always in form of "[+-]\d\d:\d\d" or "CET" or ""
]

Valid examples:

[ "2019-06-02", "12:35:45", "CET" ]
[ "2019-06-02", "12:35:45", "" ]
[ "2019-06-02", "", "" ]
[ "", "12:35:45", "" ]

Intl_UnicodeBCP47LocaleIdentifier

Ƭ Intl_UnicodeBCP47LocaleIdentifier: string

See {@link Intl.UnicodeBCP47LocaleIdentifier} or Intl - Locale identification and negotiation | MDN.

Measures

Ƭ Private Measures: Object

Type declaration

Name	Type
`days`	`86400000`
`hours`	`3600000`
`minutes`	`60000`
`months`	`2419200000`
`seconds`	`1000`
`weeks`	`604800000`
`years`	`29030400000`

OperationTypes

Ƭ Private OperationTypes: keyof Intl.DateTimeFormatOptions | "text"

RelativeTimeFormatLocaleMatcher

Ƭ Private RelativeTimeFormatLocaleMatcher: "lookup" | "best fit"

The locale matching algorithm to use.

MDN.

RelativeTimeFormatNumeric

Ƭ Private RelativeTimeFormatNumeric: "always" | "auto"

The format of output message.

MDN.

RelativeTimeFormatStyle

Ƭ Private RelativeTimeFormatStyle: "long" | "short" | "narrow"

The length of the internationalized message.

MDN.

Values

Ƭ Private Values<T>: T[keyof T]

Type parameters

Name
`T`

ary_ianna_time_offsets

Ƭ Private ary_ianna_time_offsets: Object

This object stores offsets in ary_ianna_time_zones (time offsets as keys) and one corresponding index.

So for exmple, ary_ianna_time_offsets["-01:00"] is equal to 238 which is index of ary_ianna_time_zones[238]==='Atlantic/Cape_Verde' (always "-01:00").

Type declaration

Name	Type
`+01:00`	`15`
`+02:00`	`8`
`+03:00`	`270`
`+04:00`	`306`
`+04:30`	`191`
`+05:00`	`221`
`+05:30`	`173`
`+05:45`	`194`
`+06:00`	`207`
`+06:30`	`232`
`+07:00`	`182`
`+08:00`	`220`
`+08:30`	`210`
`+08:45`	`249`
`+09:00`	`176`
`+09:30`	`248`
`+10:00`	`229`
`+11:00`	`314`
`+12:00`	`345`
`+13:00`	`316`
`+14:00`	`326`
`-01:00`	`238`
`-02:00`	`242`
`-03:00`	`107`
`-04:00`	`49`
`-05:00`	`92`
`-06:00`	`62`
`-07:00`	`120`
`-08:00`	`337`
`-09:00`	`320`
`-09:30`	`330`
`-10:00`	`323`
`-11:00`	`332`

ary_ianna_time_offsets_keyed

Ƭ Private ary_ianna_time_offsets_keyed: Object

This object stores offsets in ary_ianna_time_zones (timezone id as keys) and one corresponding index.

So for exmple, ary_ianna_time_offsets["CET"] is equal to 284 which is index of ary_ianna_time_zones[284]==='Europe/Prague' (in winter "+01:00" and in summer "+02:00").

IMPORTANT NOTE: BST, EET, WET hasn't been validated! … idea is to behave the same way like CET

Type declaration

Name	Type
`BST`	`275`
`CEST`	`284`
`CET`	`284`
`EEST`	`264`
`EET`	`264`
`WEST`	`274`
`WET`	`274`

ary_ianna_time_zones

This array stores all time zones names (eg. 'Europe/Andorra') supported by { timeZone: ... } in second argument of Date.prototype.toLocaleString.

Original from stackoverflow.com/a/54500197.

format_object

Ƭ Private format_object: { [P in keyof Intl.DateTimeFormatOptions]: Intl.DateTimeFormatOptions[P]}

modifications

ordinal_numbers

Ƭ Private ordinal_numbers: ("th" | "st" | "nd" | "rd")[]

Internal helper array for {@link getOrdinalSuffix}.

Public Variables

_

• Const _: undefined

Alias for undefined which can be used to trigger default value of argument.

formats

• Const formats: format_arrays

Predefined formats for toString.

Public Functions

fromDate

▸ fromDate(date_instance): DateArray

Function generates DateArray from instance of Date.

$time.fromDate(new Date());

Parameters

Name	Type
`date_instance`	`Date`

Returns

DateArray

fromDateArguments

▸ fromDateArguments(): DateArray

In fact, internally uses {@link DateConstructor}. See Date() constructor - JavaScript | MDN.

Returns

DateArray

▸ fromDateArguments(value): DateArray

Parameters

Name	Type
`value`	`number` \| `string`

Returns

DateArray

▸ fromDateArguments(year, month, date?, hours?, minutes?, seconds?, ms?): DateArray

Parameters

Name	Type
`year`	`number`
`month`	`number`
`date?`	`number`
`hours?`	`number`
`minutes?`	`number`
`seconds?`	`number`
`ms?`	`number`

Returns

DateArray

fromNow

▸ fromNow(): DateArray

Function generates DateArray from current date/time.

Warning: Internally uses toISOString method so result is always converted to "+00:00": p($time.fromNow, $time.setTimeZone("+02:00"), $time.toString())() (p is some pipe function) — this returns "2019-07-10T16:48:43+02:00" instead of "2019-07-10T18:48:43+02:00" (current time) … the flow is "2019-07-10T18:48:43+02:00"-fromNow->"2019-07-10T16:48:43Z"-setTimeZone->"2019-07-10T16:48:43+02:00".

Returns

DateArray

fromString

▸ fromString(timestamp_string?, timezone?): DateArray

Function generates DateArray from passed string.

$time.fromString("2019-06-02 12:35:45 +01:00");
$time.fromString("2019-06-02");
$time.fromString("12:35:45");
//…
$time.fromString("2019-06-02T12:35:45+01:00");
//…
$time.fromString("12:35:45+01:00 2019-06-02")
//…

Parameters

Name	Type	Description
`timestamp_string?`	`string`	If `undefined` returns result of fromNow. Otherwise, supported forms are combinations of date ("YYYY-MM-DD", "DD/MM/YYYY"), time ("HH:mm:ss", "HH:mm") and timezone ("CET", "+01:00", "-02:00", ...):
`timezone?`	`ary_ianna_time_zones`	-

Returns

DateArray

getCETOffset

▸ getCETOffset(date_array): keyof ary_ianna_time_offsets | "Z"

Parameters

Name	Type
`date_array`	`DateArray`

Returns

keyof ary_ianna_time_offsets | "Z"

getCurrentTimeZone

▸ getCurrentTimeZone(options?): string

Timezone name/identificator (with offset) for current timezone

Parameters

Name	Type	Description
`options?`	`Object`	-
`options.description`	`"long"` \| `"none"` \| `"short"` \| `"ianna"` \| `"IANNA"`	Defaults to "long" - `"none"` skip description - `"long"` (e.g., `British Summer Time`) - `"short"` (e.g., `GMT+1`) - `"ianna"`/`"IANNA"` (e.g. `Europe/Prague`): `locale` has no effect for this
`options.locale?`	`Intl_UnicodeBCP47LocaleIdentifier`	Defaults to "en-GB"
`options.offset`	`boolean`	Defaults to `false` Show offset part: `"UTC+01:00 (…)"` or `"UTC+01:00"` (if `description="none"`)

Returns

string

getDiff

▸ getDiff(reference_date_array, output_measure_string, full_precision): (target_date_array: DateArray) => number

Returns date/times difference in output_measure_string.

Parameters

Name	Type
`reference_date_array`	`DateArray`
`output_measure_string`	keyof `Measures`
`full_precision`	`boolean`

Returns

fn

▸ (target_date_array): number

Returns date/times difference in output_measure_string.

Parameters

Name	Type
`target_date_array`	`DateArray`

Returns

number

getRelative

▸ getRelative(ms_diff, options?): string

Returns string representation of time difference (fallbacks into simplfy english version – see internal function getRelativeBackup).

Parameters

Name	Type
`ms_diff`	`number`
`options?`	`toRelativeOptions`

Returns

string

getTimeZone

▸ getTimeZone(date_array, options): string

Timezone name/identificator (with offset)

Parameters

Name	Type	Description
`date_array`	`DateArray`	-
`options`	`Object`	-
`options.description`	`"long"` \| `"none"` \| `"short"`	Defaults to "long" - `"none"` skip description - `"long"` (e.g., `British Summer Time`) - `"short"` (e.g., `GMT+1`)
`options.locale?`	`Intl_UnicodeBCP47LocaleIdentifier`	Defaults to "en-GB"
`options.offset`	`boolean`	Defaults to `false` Show offset part: `"UTC+01:00 (…)"` or `"UTC+01:00"` (if `description="none"`)

Returns

string

getTimeZoneOffset

▸ getTimeZoneOffset(date_array, timeZone): number

Parameters

Name	Type
`date_array`	`DateArray`
`timeZone`	`string`

Returns

number

getTimeZoneOffsetString

▸ getTimeZoneOffsetString(date_array): string

Parameters

Name	Type
`date_array`	`DateArray`

Returns

string

getTimeZones

▸ getTimeZones(): ary_ianna_time_zones[]

Returns

ary_ianna_time_zones[]

isTimeZone

▸ isTimeZone(candidate): boolean

Parameters

Name	Type
`candidate`	`string`

Returns

boolean

modify

▸ modify(mod_obj): (date_array: DateArray) => DateArray

Curried method, first invocation sets operations (i. e. { addDay: 1 }) and returns (date_array: DateArray)=> DateArray.
- object literal representing requested operations
- use name convention like setters for Date (only one argument is allowed)
- supports also add* commands with the same notation ("setMonth" => "addMonth")
- IMPORTANT NOTE: There are three behaviour changes
  - "setMonth" is indexed from 1 (instead of 0)
  - for "setDate" there is alias "setDay"
  - for "addDate" there is alias "addDays"

Parameters

Name	Type
`mod_obj`	`Record`<`modifications`, `number`>

Returns

fn

▸ (date_array): DateArray

Parameters

Name	Type
`date_array`	`DateArray`

Returns

DateArray

setInternalLocale

▸ setInternalLocale<L>(locale): L

If setted into undefined tries to follow user device configuration.

Type parameters

Name	Type
`L`	extends `string`

Parameters

Name	Type
`locale`	`L`

Returns

L

setInternalZone

▸ setInternalZone(zone): string

Parameters

Name	Type
`zone`	`string`

Returns

string

toDate

▸ toDate(date_array?): Date

Defaults to new Date(), or if filled partialy defaults to current date/00:00:00/current zone.

Parameters

Name	Type
`date_array?`	`DateArray`

Returns

Date

toLocaleString

▸ toLocaleString(format_object_name, options?): (date_array: DateArray) => string

It is wrapper arround Date.prototype.toLocaleString.

Parameters

Name	Type
`format_object_name`	keyof `format_objects`
`options?`	`toLocaleStringOptions`

Returns

fn

▸ (date_array): string

It is wrapper arround Date.prototype.toLocaleString.

Parameters

Name	Type
`date_array`	`DateArray`

Returns

string

toRelative

▸ toRelative(reference_date_array, options?): (target_date_array: DateArray) => string

Curried function of getRelative.

Parameters

Name	Type
`reference_date_array`	`DateArray`
`options?`	`toRelativeOptions`

Returns

fn

▸ (target_date_array): string

Curried function of getRelative.

Parameters

Name	Type
`target_date_array`	`DateArray`

Returns

string

toString

▸ toString(format, options?): (date_array: DateArray) => string

Function generates text based on format, locale and timeZone from DateArray.

$time.toString("DD/MM/YYYY HH:mm:SS",{ locale: "en-GB" })($time.fromNow());//= "05/06/2019 09:32:20"
$time.toString($time.formats.SQL)($time.fromNow());//= "2019-06-05 09:32:20"

Parameters

Name	Type	Description
`format`	`string` \| `Values`<`format_arrays`>	For using `string` see getFormatObject, else $time.formats.
`options?`	`toLocaleStringOptions`	-

Returns

fn

▸ (date_array): string

Function generates text based on format, locale and timeZone from DateArray.

$time.toString("DD/MM/YYYY HH:mm:SS",{ locale: "en-GB" })($time.fromNow());//= "05/06/2019 09:32:20"
$time.toString($time.formats.SQL)($time.fromNow());//= "2019-06-05 09:32:20"

Parameters

Name	Type
`date_array`	`DateArray`

Returns

string

Private Functions

getFormatObject

▸ Private getFormatObject(format_string?): ArrayOfOperations

Generates multidimensional array for formatting (eg. "YYYY"=> [ [ "year", "numeric" ] ]). Supports:
- "YYYY", "YY",
- "MM", "MMM", "MMMM",
- "dddd" (weekday - Monday), "ddd" (shorter weekday - Mon), "dd" (Mo), "d" (0===Sun <> 6===Sat),
- "DD", "D", "Do",
- "HH", "H",
- "mm", "m",
- "SS", "S",
- "W", "Wo"

Parameters

Name	Type
`format_string?`	`string`

Returns

ArrayOfOperations

FilesExpand file tree

_time.md

Latest commit

History

_time.md

File metadata and controls

Namespace: $time

Table of contents

Public Namespaces

Interfaces

Type aliases

Public Variables

Public Functions

Private Functions

Type aliases

ArrayOfOperation

Type parameters

ArrayOfOperations

DateArray

Intl_UnicodeBCP47LocaleIdentifier

Measures

Type declaration

OperationTypes

RelativeTimeFormatLocaleMatcher

RelativeTimeFormatNumeric

RelativeTimeFormatStyle

Values

Type parameters

ary_ianna_time_offsets

Type declaration

ary_ianna_time_offsets_keyed

Type declaration

ary_ianna_time_zones

format_object

modifications

ordinal_numbers

Public Variables

_

formats

Public Functions

fromDate

Parameters

Returns

fromDateArguments

Returns

Parameters

Returns

Parameters

Returns

fromNow

Returns

fromString

Parameters

Returns

getCETOffset

Parameters

Returns

getCurrentTimeZone

Parameters

Returns

getDiff

Parameters

Returns

Parameters

Returns

getRelative

Parameters

Returns

getTimeZone

Parameters

Returns

getTimeZoneOffset

Parameters

Returns

getTimeZoneOffsetString

Parameters

Returns

getTimeZones

Returns

isTimeZone