📝 Updated docs

README.md

@@ -1,7 +1,7 @@
 <div align="center" style="text-align: center;">
   <h1 style="border-bottom: none;">@motss/utc-date</h1>
 
-  <p>Better greeting message</p>
+  <p>Generate JavaScript's UTC dates with various offsets</p>
 </div>
 
 <hr />
@@ -16,25 +16,28 @@
 [![NSP Status][nsp-badge]][nsp-url]
 
 [![Code of Conduct][coc-badge]][coc-url]
+[![Codecov][codecov-badge]][codecov-url]
+[![Coverage Status][coveralls-badge]][coveralls-url]
 
 [![codebeat-badge]][codebeat-url]
 [![codacy-badge]][codacy-url]
 [![inch-badge]][inch-url]
 
-> Generate JavaScript's UTC dates with various offsets
+> Returns a [JavaScript date object][date-mdn-url] using the [UTC][utc-url] timezone with optional offsets to adjust the `year`, `month`, or `date`.
 
 ## Table of contents
 
-- [Pre-requisite](#pre-requisite)
-- [Setup](#setup)
-  - [Install](#install)
-  - [Usage](#usage)
-    - [Node.js](#nodejs)
-    - [Native ES modules or TypeScript](#native-es-modules-or-typescript)
-- [API Reference](#api-reference)
-  - [greeting(name)](#greetingname)
-  - [greetingSync(name)](#greetingsyncname)
-- [License](#license)
+  - [Pre-requisites](#pre-requisites)
+  - [Setup](#setup)
+    - [Install](#install)
+    - [Usage](#usage)
+      - [Node.js](#nodejs)
+      - [Native ES modules or TypeScript](#native-es-modules-or-typescript)
+  - [API Reference](#api-reference)
+    - [UTCDateOpts](#utcdateopts)
+    - [utcDate([UTCDateOpts])](#utcdateutcdateoptsutc-date-opts-url)
+    - [utcDateSync([UTCDateOpts])](#utcdatesyncutcdateoptsutc-date-opts-url)
+  - [License](#license)
 
 ## Pre-requisites
 
@@ -55,27 +58,79 @@ $ npm install --save @motss/utc-date
 #### Node.js
 
 ```js
-const greeting = require('@motss/utc-date');
+const {
+  utcDate,
+  // utcDateSync,
+} = require('@motss/utc-date');
+
+void async function main() {
+  /** NOTE: Assuming today's date is '2020-02-02', */
+  const defaultUTCDate = await utcDate(); // utcDateSync();
+  const defaultUTCDateWithOffsets = await utcDate({
+    offset: {
+      year: 2,
+      month: 1,
+      date: 0,
+    },
+  });
+  const specifiedUTCDate = await utcDate({
+    startDate: '2030-03-02',
+  });
+
+  assert(defaultUTCDate, new Date('2020-02-02T00:00:00.000Z')); // OK
+  assert(defaultUTCDateWithOffsets, new Date('2022-03-02T00:00:00.000Z')); // OK
+  assert(specifiedUTCDate, new Date('2030-03-02T00:00:00.000Z')); // OK
+}();
 ```
 
 #### Native ES modules or TypeScript
 
 ```ts
 // @ts-check
 
-import greeting from '@motss/utc-date';
+import {
+  utcDate,
+  // utcDateSync,
+} from '@motss/utc-date';
+
+void async function main() {
+  /** NOTE: Assuming today's date is '2020-02-02', */
+  const defaultUTCDate = await utcDate();
+  const defaultUTCDateWithOffsets = await utcDate({
+    offset: {
+      year: 2,
+      month: 1,
+      date: 0,
+    },
+  });
+  const specifiedUTCDate = await utcDate({
+    startDate: '2030-03-02',
+  });
+
+  assert(defaultUTCDate, new Date('2020-02-02T00:00:00.000Z')); // OK
+  assert(defaultUTCDateWithOffsets, new Date('2022-03-02T00:00:00.000Z')); // OK
+  assert(specifiedUTCDate, new Date('2030-03-02T00:00:00.000Z')); // OK
+}();
 ```
 
 ## API Reference
 
-### greeting(name)
+### UTCDateOpts
 
-  - name <[string][string-mdn-url]> Name of the person to greet at.
-  - returns: <[Promise][promise-mdn-url]&lt;[string][string-mdn-url]&gt;> Promise which resolves with a greeting message.
+ - `offsets` <[Object][object-mdn-url]> Optional offset values when returning a [JavaScript Date object][date-mdn-url] using the [UTC][utc-url] timezone.
+    - `year` <[number][number-mdn-url]> Optional offset to adjust the `year`.
+    - `month` <[number][number-mdn-url]> Optional offset to adjust the `month`.
+    - `date` <[number][number-mdn-url]> Optional offset to adjust the `date`.
+- `startDate` <[string][string-mdn-url]|[number][number-mdn-url]|[Date][date-mdn-url]> Optional starting date. _Defaults to today's date if it is not given._
 
-### greetingSync(name)
+### utcDate([[UTCDateOpts][utc-date-opts-url]])
 
-This methods works the same as `greeting(name)` except that this is the synchronous version.
+  - `UTCDateOpts` <[UTCDateOpts][utc-date-opts-url]> Optional configuration when returning a [JavaScript Date object][date-mdn-url] using the [UTC][utc-url] timezone.
+  - returns: <[Promise][promise-mdn-url]&lt;[string][string-mdn-url]&gt;> Promise which resolves with a [JavaScript Date object][date-mdn-url] using the [UTC][utc-url] timezone.
+
+### utcDateSync([[UTCDateOpts][utc-date-opts-url]])
+
+This methods works the same as `utcDate([UTCDateOpts])` except that this is the synchronous version.
 
 ## License
 
@@ -87,9 +142,13 @@ This methods works the same as `greeting(name)` except that this is the synchron
 [node-js-url]: https://nodejs.org
 [npm-url]: https://www.npmjs.com
 [node-releases-url]: https://nodejs.org/en/download/releases
+[utc-url]: https://en.wikipedia.org/wiki/Coordinated_Universal_Time
+
+[utc-date-opts-url]: #utcdateopts
 
 [array-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array
 [boolean-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+[date-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date
 [function-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function
 [map-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map
 [number-mdn-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number
@@ -101,20 +160,22 @@ This methods works the same as `greeting(name)` except that this is the synchron
 
 
 
-[nodei-badge]: https://nodei.co/npm/utc-date.png?downloads=true&downloadRank=true&stars=true
+[nodei-badge]: https://nodei.co/npm/@motss/utc-date.png?downloads=true&downloadRank=true&stars=true
 
 [travis-badge]: https://img.shields.io/travis/motss/utc-date.svg?style=flat-square
 
-[version-badge]: https://img.shields.io/npm/v/utc-date.svg?style=flat-square
-[downloads-badge]: https://img.shields.io/npm/dm/utc-date.svg?style=flat-square
+[version-badge]: https://img.shields.io/npm/v/@motss/utc-date.svg?style=flat-square
+[downloads-badge]: https://img.shields.io/npm/dm/@motss/utc-date.svg?style=flat-square
 [mit-license-badge]: https://img.shields.io/github/license/mashape/apistatus.svg?style=flat-square
-[nsp-badge]: https://nodesecurity.io/orgs/motss/projects/a1c57ec8-9c17-4912-932b-f1ff6284e2ae/badge?style=flat-square
+[nsp-badge]: https://nodesecurity.io/orgs/motss/projects/f7a6646b-202f-4b73-ad9e-6f6eacc577de/badge?style=flat-square
 [daviddm-badge]: https://img.shields.io/david/motss/utc-date.svg?style=flat-square
 
 [coc-badge]: https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square
+[codecov-badge]: https://codecov.io/gh/motss/utc-date/branch/master/graph/badge.svg?style=flat-square
+[coveralls-badge]: https://coveralls.io/repos/github/motss/utc-date/badge.svg?branch=master&style=flat-square
 
-[codebeat-badge]: https://codebeat.co/badges/e486e791-12b7-4198-b834-0fa5bd04e1c3?style=flat-square
-[codacy-badge]: https://api.codacy.com/project/badge/Grade/a70d1556b4e74711a162c4fd4dbb68a1?style=flat-square
+[codebeat-badge]: https://codebeat.co/badges/1ed02b65-dca8-45a5-8719-cdead763a617?style=flat-square
+[codacy-badge]: https://api.codacy.com/project/badge/Grade/1d15da734ee5424c8981d7e3e4d74c18?style=flat-square
 [inch-badge]: http://inch-ci.org/github/motss/utc-date.svg?branch=master&style=flat-square
 
 
@@ -125,10 +186,12 @@ This methods works the same as `greeting(name)` except that this is the synchron
 [version-url]: https://npmjs.org/package/utc-date
 [downloads-url]: http://www.npmtrends.com/utc-date
 [mit-license-url]: https://github.com/motss/utc-date/blob/master/LICENSE
-[nsp-url]: https://nodesecurity.io/orgs/motss/projects/a1c57ec8-9c17-4912-932b-f1ff6284e2ae
+[nsp-url]: https://nodesecurity.io/orgs/motss/projects/f7a6646b-202f-4b73-ad9e-6f6eacc577de
 [daviddm-url]: https://david-dm.org/motss/utc-date
 
 [coc-url]: https://github.com/motss/utc-date/blob/master/CODE_OF_CONDUCT.md
+[codecov-url]: https://codecov.io/gh/motss/utc-date
+[coveralls-url]: https://coveralls.io/github/motss/utc-date?branch=master
 
 [codebeat-url]: https://codebeat.co/projects/github-com-motss-utc-date-master
 [codacy-url]: https://www.codacy.com/app/motss/utc-date?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=motss/utc-date&amp;utm_campaign=Badge_Grade

package.json

@@ -4,9 +4,12 @@
   "private": true,
   "description": "Generate JavaScript's UTC dates with various offsets",
   "keywords": [
+    "date-offset",
     "node",
     "typescript",
-    "utc-date"
+    "utc",
+    "utc-date",
+    "utc-datetime"
   ],
   "homepage": "https://github.com/motss/utc-date",
   "license": "MIT",

src/index.ts

@@ -5,16 +5,16 @@ export declare interface UTCDateOffset {
   month?: number;
   date?: number;
 }
-export declare interface UTCDateParams {
+export declare interface UTCDateOpts {
   offset?: UTCDateOffset;
-  startDate?: Date | string | number;
+  startDate?: string | number | Date;
 }
 
 export function isValidDate(anyDate: any) {
   return !/^invalid date/i.test(`${new Date(anyDate)}`);
 }
 
-export async function utcDate(opts: UTCDateParams = {} as UTCDateParams) {
+export async function utcDate(opts: UTCDateOpts = {} as UTCDateOpts) {
   try {
     return await utcDateSync(opts);
   } catch (e) {
@@ -25,7 +25,7 @@ export async function utcDate(opts: UTCDateParams = {} as UTCDateParams) {
 export function utcDateSync({
   offset = { year: 0, month: 0, date: 0 },
   startDate,
-}: UTCDateParams = {} as UTCDateParams) {
+}: UTCDateOpts = {} as UTCDateOpts) {
   const isNullishDate = startDate == null;
 
   if (!isNullishDate && !isValidDate(startDate)) {