convert formatISO to TypeScript (date-fns#2593)

src/formatISO/index.js → src/formatISO/index.ts

@@ -1,32 +1,33 @@
 import toDate from '../toDate/index'
-import isValid from '../isValid/index'
+import type { FormatOptions, RepresentationOptions } from '../types'
 import addLeadingZeros from '../_lib/addLeadingZeros/index'
+import requiredArgs from '../_lib/requiredArgs'
 
 /**
  * @name formatISO
  * @category Common Helpers
- * @summary Format the date according to the ISO 8601 standard (http://support.sas.com/documentation/cdl/en/lrdict/64316/HTML/default/viewer.htm#a003169814.htm).
+ * @summary Format the date according to the ISO 8601 standard (https://support.sas.com/documentation/cdl/en/lrdict/64316/HTML/default/viewer.htm#a003169814.htm).
  *
  * @description
  * Return the formatted date string in ISO 8601 format. Options may be passed to control the parts and notations of the date.
  *
  * @param {Date|Number} date - the original date
  * @param {Object} [options] - an object with options.
  * @param {'extended'|'basic'} [options.format='extended'] - if 'basic', hide delimiters between date and time values.
- * @param {'complete'|'date'|'time'} [options.representation='complete'] - format date, time with time zone, or both.
- * @returns {String} the formatted date string
+ * @param {'complete'|'date'|'time'} [options.representation='complete'] - format date, time with local time zone, or both.
+ * @returns {String} the formatted date string (in local time zone)
  * @throws {TypeError} 1 argument required
  * @throws {RangeError} `date` must not be Invalid Date
  * @throws {RangeError} `options.format` must be 'extended' or 'basic'
  * @throws {RangeError} `options.represenation` must be 'date', 'time' or 'complete'
  *
  * @example
- * // Represent 18 September 2019 in ISO 8601 format (UTC):
+ * // Represent 18 September 2019 in ISO 8601 format (local time zone is UTC):
  * const result = formatISO(new Date(2019, 8, 18, 19, 0, 52))
  * //=> '2019-09-18T19:00:52Z'
  *
  * @example
- * // Represent 18 September 2019 in ISO 8601, short format (UTC):
+ * // Represent 18 September 2019 in ISO 8601, short format (local time zone is UTC):
  * const result = formatISO(new Date(2019, 8, 18, 19, 0, 52), { format: 'basic' })
  * //=> '20190918T190052'
  *
@@ -36,27 +37,26 @@ import addLeadingZeros from '../_lib/addLeadingZeros/index'
  * //=> '2019-09-18'
  *
  * @example
- * // Represent 18 September 2019 in ISO 8601 format, time only (UTC):
+ * // Represent 18 September 2019 in ISO 8601 format, time only (local time zone is UTC):
  * const result = formatISO(new Date(2019, 8, 18, 19, 0, 52), { representation: 'time' })
  * //=> '19:00:52Z'
  */
-export default function formatISO(dirtyDate, dirtyOptions) {
-  if (arguments.length < 1) {
-    throw new TypeError(
-      `1 argument required, but only ${arguments.length} present`
-    )
-  }
+export default function formatISO(
+  date: Date | number,
+  options?: FormatOptions & RepresentationOptions
+): string {
+  requiredArgs(1, arguments)
 
-  const originalDate = toDate(dirtyDate)
+  const originalDate = toDate(date)
 
-  if (!isValid(originalDate)) {
+  if (isNaN(originalDate.getTime())) {
     throw new RangeError('Invalid time value')
   }
 
-  const options = dirtyOptions || {}
-  const format = options.format == null ? 'extended' : String(options.format)
-  const representation =
-    options.representation == null ? 'complete' : String(options.representation)
+  const format = !options?.format ? 'extended' : String(options.format)
+  const representation = !options?.representation
+    ? 'complete'
+    : String(options.representation)
 
   if (format !== 'extended' && format !== 'basic') {
     throw new RangeError("format must be 'extended' or 'basic'")

src/formatISO/test.js → src/formatISO/test.ts

@@ -1,13 +1,12 @@
-// @flow
 /* eslint-env mocha */
 
-import assert from 'power-assert'
+import assert from 'assert'
 import sinon from 'sinon'
 import formatISO from '.'
 import addLeadingZeros from '../_lib/addLeadingZeros'
 
 // This makes sure we create the consistent offsets across timezones, no matter where these tests are ran.
-function generateOffset(originalDate) {
+function generateOffset(originalDate: Date) {
   // Add the timezone.
   let offset = ''
   const tzOffset = originalDate.getTimezoneOffset()
@@ -96,8 +95,12 @@ describe('formatISO', () => {
       var format = new String('basic')
       var date = new Date(2019, 9 /* Oct */, 4, 12, 30, 13, 456)
       const tzOffsetExtended = generateOffset(date)
-      // $ExpectedMistake
-      var result = formatISO(date, { format: format })
+
+      const result = formatISO(
+        date,
+        // @ts-expect-error
+        { format: format }
+      )
       assert(result === `20191004T123013${tzOffsetExtended}`)
     })
 
@@ -106,22 +109,26 @@ describe('formatISO', () => {
       var representation = new String('time')
       var date = new Date(2019, 9 /* Oct */, 4, 12, 30, 13, 456)
       const tzOffsetExtended = generateOffset(date)
-      // $ExpectedMistake
-      var result = formatISO(date, { representation: representation })
+
+      const result = formatISO(
+        date,
+        // @ts-expect-error
+        { representation: representation }
+      )
       assert(result === `12:30:13${tzOffsetExtended}`)
     })
   })
 
   it("throws `RangeError` if `options.format` is not 'extended' or 'basic'", function () {
-    // $ExpectedMistake
+    // @ts-expect-error
     var block = formatISO.bind(null, new Date(2019, 2 /* Mar */, 3), {
       format: 'something else',
     })
     assert.throws(block, RangeError)
   })
 
   it("throws `RangeError` if `options.representation` is not 'date', 'time' or 'complete'", function () {
-    // $ExpectedMistake
+    // @ts-expect-error
     var block = formatISO.bind(null, new Date(2019, 2 /* Mar */, 3), {
       representation: 'something else',
     })
@@ -133,6 +140,7 @@ describe('formatISO', () => {
   })
 
   it('throws TypeError exception if passed less than 1 argument', function () {
+    // @ts-expect-error
     assert.throws(formatISO.bind(null), TypeError)
   })
 })

src/types.ts

@@ -31,6 +31,14 @@ export interface LocaleOptions {
   locale?: Locale
 }
 
+export interface FormatOptions {
+  format?: 'extended' | 'basic'
+}
+
+export interface RepresentationOptions {
+  representation?: 'complete' | 'date' | 'time'
+}
+
 export type Era = 0 | 1
 
 export type Quarter = 1 | 2 | 3 | 4
@@ -41,10 +49,6 @@ export type Month = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11
 
 export type FirstWeekContainsDate = 1 | 4
 
-export interface FirstWeekContainsDateOptions {
-  firstWeekContainsDate?: FirstWeekContainsDate
-}
-
 export interface DateValues {
   year?: number
   month?: number