Skip to content

Latest commit

 

History

History
357 lines (286 loc) · 16.9 KB

API.md

File metadata and controls

357 lines (286 loc) · 16.9 KB
Raw

API Reference

The API consists of functions only. They are divided to three modules, which you can load separately or together depending on your usage scenario.

Table of Contents

Loading

Load the main module in an application using CommonJS modules:

const {
  convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone
 } = require('date-fns-timezone')

Load only specific modules in an application using CommonJS modules:

const { convertToLocalTime } = require('date-fns-timezone/dist/convertToLocalTime')
const { convertToTimeZone } = require('date-fns-timezone/dist/convertToTimeZone')
const { parseFromTimeZone } = require('date-fns-timezone/dist/parseFromTimeZone')
const { formatToTimeZone } = require('date-fns-timezone/dist/formatToTimeZone')

Load the main module in an application using ES6 modules:

import {
  convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone
} from './node_modules/date-fns-timezone/src/index.js'

Load only specific modules in an application using ES6 modules:

import { convertToLocalTime } from './node_modules/date-fns-timezone/src/convertToLocalTime.js'
import { convertToTimeZone } from './node_modules/date-fns-timezone/src/convertToTimeZone.js'
import { parseFromTimeZone } from './node_modules/date-fns-timezone/src/parseFromTimeZone.js'
import { formatToTimeZone } from './node_modules/date-fns-timezone/src/formatToTimeZone.js'

Load the main module in the browser with plain JavaScript:

<script src="https://cdnjs.cloudflare.com/ajax/libs/date-fns/1.29.0/date_fns.min.js"></script>
<script src="./node_modules/timezone-support/dist/index.umd.js"></script>
<script src="./node_modules/date-fns-timezone/dist/index.umd.js"></script>
<script>
  (() => {
    const {
      convertToLocalTime, convertToTimeZone, parseFromTimeZone, formatToTimeZone
    } = window.dateFnsTimezone
  })()
</script>

Load the main module in the browser with [RequireJS]:

<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/date-fns/1.29.0/date_fns.min.js"></script>
<script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script>
<script src="https://unpkg.com/[email protected]/dist/index.umd.js"></script>
<script>
  require(['date-fns-timezone'], ({ parseFromTimeZone, formatToTimeZone }) => {
  })
</script>

The last example shows also, how to load a specific version of the library from CDN.

Modules

Modules in the src directory require ES6 including the new module syntax, as available in Node.js 8 and newer. Modules in the dist directory require ES5 and follow the CommonJS standard for older Node.js releases. Files dist/*.umd.js require ES5, are minified and follow the UMD standard to work well in web browsers.

Except for the index module including all functions, each function is exposed in a separate module with the same name as the function name and .js and .umd.js suffixes. You can load the separate modules, if you cannot use a bundler supporting tree-shaking for the size optimization.

index.js

Main package module for Node.js application. CommonJS format. Includes all functions from the other modules.

index.umd.js

Main package module first of all for web browsers. UMD format, minified. Includes all functions from the other modules. Make sure, that you include script elements for date-fns and timezone-support on your web page before this one as documented earlier.

Functions

Functions converting to an arbitrary time zone accept either a Date object, or a UNIX timestamp. (The UNIX timestamp is the time from the epoch in milliseconds, as returned by date.prototype.getTime.) They produce a complete time object. Functions converting from an arbitrary time zone accept a time object and return the UNIX timestamp.

convertToLocalTime

convertToLocalTime(date: Date|string|number, options: object) : Date

Converts the given date from the given time zone to the local time and returns it as a new Date object. Getters for local time parts of the input Date object (getFullYear, getMonth, ...) will be assumed to return time in the given time zone.

  • argument (Date|String|Number) - the value to convert
  • options (Object) - the object with options
  • options.timeZone (String) - the canonical name of the source time zone

The time zone has to be specified as a canonical name from the IANA time zone list.

const { convertToLocalTime } = require('date-fns-timezone')
// Convert the time in the New York time zone to the local time:
const date = new Date(2018, 8, 2, 10, 0)
const result = convertToLocalTime(date, { timeZone: 'America/New_York' })
// Returns { date: Date, zone: { abbreviation: 'EDT', offset: -360 }
// The date will be "2018-09-02T16:00:00Z".

convertToTimeZone

convertToTimeZone(date: Date|number|string, options: object) : Date

Converts the given date from the local time to the given time zone and returns a new Date object, which has its local time set to it. The returned Date object should not be used form comparisons or other computations. Only the its getters for the local time parts can be used (getFullYear, getMonth, ...).

  • argument (Date|String|Number) - the value to convert
  • options (Object) - the object with options
  • options.timeZone (String) - the canonical name of the target time zone

The time zone has to be specified as a canonical name from the IANA time zone list.

const { convertToTimeZone } = require('date-fns-timezone')
// Convert the current local time to the New York time zone:
var result = convertToTimeZone(new Date(), { timeZone: 'America/New_York' })
// Returns { date: Date, zone: { abbreviation: 'EST', offset: -300 }

formatToTimeZone

formatToTimeZone(date: Date|string|number, format: string, options: object) : string

Returns the formatted date string in the given format, after converting it to the given time zone.

The input date will be converted to the given time zone by default, using its UTC timestamp. If the local time in the input date is already in the given time zone, set options.convertTimeZone to false. Otherwise the date will be considered in local time and converted.

  • argument (Date|String|Number) - the original date
  • format (String) - the string of formatting tokens
  • options (Object) - the object with options
  • options.locale (Object) - the locale object; optional, defaults to English
  • options.timeZone (String) - the canonical name of the target time zone
  • options.convertTimeZone (Boolean) - if the date should be converted to the given time zone before formatting; optional, defaults to true

The locale can be loaded and applied in the same way, as it works for the function format from date-fns.

The time zone has to be specified as a canonical name from the IANA time zone list.

The following tokens are recognized in the format string:

Unit Token Result examples
Month M 1, 2, ..., 12
Mo 1st, 2nd, ..., 12th
MM 01, 02, ..., 12
MMM Jan, Feb, ..., Dec
MMMM January, February, ..., December
Quarter Q 1, 2, 3, 4
Qo 1st, 2nd, 3rd, 4th
Day of month D 1, 2, ..., 31
Do 1st, 2nd, ..., 31st
DD 01, 02, ..., 31
Day of year DDD 1, 2, ..., 366
DDDo 1st, 2nd, ..., 366th
DDDD 001, 002, ..., 366
Day of week d 0, 1, ..., 6
do 0th, 1st, ..., 6th
dd Su, Mo, ..., Sa
ddd Sun, Mon, ..., Sat
dddd Sunday, Monday, ..., Saturday
Day of ISO week E 1, 2, ..., 7
ISO week W 1, 2, ..., 53
Wo 1st, 2nd, ..., 53rd
WW 01, 02, ..., 53
Year YY 00, 01, ..., 99
YYYY 1900, 1901, ..., 2099
ISO week-numbering year GG 00, 01, ..., 99
GGGG 1900, 1901, ..., 2099
AM/PM A AM, PM
a am, pm
aa a.m., p.m.
Hour H 0, 1, ... 23
HH 00, 01, ... 23
h 1, 2, ..., 12
hh 01, 02, ..., 12
Minute m 0, 1, ..., 59
mm 00, 01, ..., 59
Second s 0, 1, ..., 59
ss 00, 01, ..., 59
1/10 of second S 0, 1, ..., 9
1/100 of second SS 00, 01, ..., 99
Millisecond SSS 000, 001, ..., 999
Timezone abbreviation z CET, CEST, EST, EDT, ...
Timezone offset to UTC Z -01:00, +00:00, ... +12:00
ZZ -0100, +0000, ..., +1200
Seconds timestamp X 512969520
Milliseconds timestamp x 512969520900

To escape characters in the format string, wrap them in square brackets (e.g. [GMT]). Punctuation symbols (-:/.()) do not need to be wrapped.

const { formatToTimeZone } = require('date-fns-timezone')
// Represent midnight on 11 February 2014, UTC in middle-endian format, New York time:
const result = formatToTimeZone(
  new Date(Date.UTC(2014, 1, 11)), 'MM/dd/yyyy h:mm A [GMT]Z (z)',
  { timeZone: 'America/New_York' }
)
// Returns '02/10/2014 7:00 PM GMT-0500 (EST)'
// Represent noon on 2 July 2014 in Esperanto, Madrid time:
const { formatToTimeZone } = require('date-fns-timezone')
const locale = require('date-fns/locale/eo')
const result = formatToTimeZone(
  new Date(2014, 6, 2, 12), "HH:mm, do 'de' MMMM yyyy (Zz)",
  { locale, timeZone: 'Europe/Madrid', convertTimeZone: false }
)
// Returns '12:00, 2-a de julio 2014 (+02:00 CEST)'

parseFromString

parseFromString(input: string, format: string) : Date

Returns the date parsed from the date string using the given format string and converts the parsed date to the local time.

  • input (String) - the string to parse
  • format (String) - the custom format to parse the date from

The following tokens are recognized in the format string:

Token Input example Description
YY 18 Two-digit year
YYYY 2018 Four-digit year
M 1-12 Month, beginning at 1
MM 01-12 Month, 2-digits
D 1-31 Day of month
DD 01-31 Day of month, 2-digits
H 0-23 Hours
HH 00-23 Hours, 2-digits
h 1-12 Hours, 12-hour clock
hh 01-12 Hours, 12-hour clock, 2-digits
m 0-59 Minutes
mm 00-59 Minutes, 2-digits
s 0-59 Seconds
ss 00-59 Seconds, 2-digits
S 0-9 Hundreds of milliseconds, 1-digit
SS 00-99 Tens of milliseconds, 2-digits
SSS 000-999 Milliseconds, 3-digits
z EST Time zone abbreviation
Z -5:00 Offset from UTC, 2-digits
ZZ -0500 Compact offset from UTC, 2-digits
A AM PM Post or ante meridiem, upper-case
a am pm Post or ante meridiem, lower-case

To escape characters in the format string, wrap them in square brackets (e.g. [G]). Punctuation symbols (-:/.()) do not need to be wrapped.

// Parse string '11.2.2014 11:30:30' to date in Berlin:
const result = parseFromTimeZone(
  '11.2.2014 11:30:30', 'D.M.YYYY H:mm:ss')
// Returns Tue Feb 11 2014 10:30:30 UTC
// Parse string '02/11/2014 11:30:30' to date, New York time:
const result = parseFromString(
  '02/11/2014 11:30:30 AM GMT-0500 (EDT)',
  'MM/DD/YYYY h:mm:ss.SSS A [GMT]ZZ (z)')
// Returns Tue Feb 11 2014 16:30:30 UTC

parseFromTimeZone

parseFromTimeZone(input: string, format?: string, options: object) : Date

Returns the date parsed from the date string, optionally using the given format string, and converts the parsed date from the given time zone to the local time.

  • input (String) - the string to parse
  • format (String) - the custom format to parse the date from; optional
  • options (Object) - the object with options
  • options.timeZone (String) - the canonical name of the source time zone

If the format string is omitted, the date string will be parsed by date-fns/parse, which supports extended ISO 8601 formats.

The time zone has to be specified as a canonical name from the IANA time zone list.

The following tokens are recognized in the format string:

Token Input example Description
YY 18 Two-digit year
YYYY 2018 Four-digit year
M 1-12 Month, beginning at 1
MM 01-12 Month, 2-digits
D 1-31 Day of month
DD 01-31 Day of month, 2-digits
H 0-23 Hours
HH 00-23 Hours, 2-digits
h 1-12 Hours, 12-hour clock
hh 01-12 Hours, 12-hour clock, 2-digits
m 0-59 Minutes
mm 00-59 Minutes, 2-digits
s 0-59 Seconds
ss 00-59 Seconds, 2-digits
S 0-9 Hundreds of milliseconds, 1-digit
SS 00-99 Tens of milliseconds, 2-digits
SSS 000-999 Milliseconds, 3-digits
z EST Time zone abbreviation
Z -5:00 Offset from UTC, 2-digits
ZZ -0500 Compact offset from UTC, 2-digits
A AM PM Post or ante meridiem, upper-case
a am pm Post or ante meridiem, lower-case

To escape characters in the format string, wrap them in square brackets (e.g. [G]). Punctuation symbols (-:/.()) do not need to be wrapped.

// Parse string '2014-02-11 11:30:30 AM' to date, New York time:
const result = parseFromTimeZone(
  '2014-02-11 11:30:30', { timeZone: 'America/New_York' })
// Returns Tue Feb 11 2014 16:30:30 UTC
// Parse string '11.2.2014 11:30:30' to date, Berlin time:
const result = parseFromTimeZone(
  '11.2.2014 11:30:30', 'D.M.YYYY H:mm:ss',
   { timeZone: 'Europe/Berlin' })
// Returns Tue Feb 11 2014 10:30:30 UTC