Get the current date in any format your project needs.

A cross-platform Node.js utility written in TypeScript that retrieves, formats, and transforms the current date.

Works identically on macOS, Linux, and Windows.

Table of Contents (TOC)

• Features
• Install
  • From npm
  • From GitHub (install into a codebase)
  • Local install (copy into codebase)
• Quick Start
• API Reference
  • getDate(options?)
  • Options
  • Return Values
• Option Reference
• Examples
• Testing
• Build
• License

Features

• Default call returns all common date components in one object
• Flexible options for every date component: day, month, quarter, year, and more
• Cross-platform — uses the Node.js Date API exclusively, no OS-specific calls
• TypeScript-first with full type declarations
• Tree-shakeable — import only what you need
• Zero runtime dependencies
• Fully tested: unit tests per option + integration suite

Install

From npm

npm install @jhauga/getdate

yarn add @jhauga/getdate

pnpm add @jhauga/getdate

From GitHub (install into a codebase)

If the package has not been published to the npm registry, install directly from the GitHub repository:

npm install github:YOUR_USERNAME/getDate

Replace YOUR_USERNAME with the GitHub user or organization that owns the repository. After running this, the package appears under node_modules/@jhauga/getdate and can be imported as normal.

To pin to a specific tag or commit:

npm install github:YOUR_USERNAME/getDate#v1.0.1

Local install (copy into codebase)

Clone or download the repository, then install it as a local package:

# 1. Clone the repo next to your project
git clone https://github.com/YOUR_USERNAME/getDate.git

# 2. Build it
cd getDate
npm install
npm run build

# 3. Install it into your project
cd ../your-project
npm install ../getDate

Or reference it with a relative path directly in your package.json:

{
  "dependencies": {
    "@jhauga/getdate": "file:../getDate"
  }
}

Then run npm install.

Adding to your project's package.json

Rather than running an install command, you can add the dependency directly to your project's package.json and then run npm install.

When published to the npm registry:

{
  "dependencies": {
    "@jhauga/getdate": "^1.0.1"
  }
}

When not yet published (GitHub source):

{
  "dependencies": {
    "@jhauga/getdate": "github:YOUR_USERNAME/getDate"
  }
}

To pin to a specific release tag or commit:

{
  "dependencies": {
    "@jhauga/getdate": "github:YOUR_USERNAME/getDate#v1.0.1"
  }
}

After editing package.json, run:

npm install

Quick Start

import { getDate } from '@jhauga/getdate';

// Default call — returns all common date values
const result = getDate();
console.log(result.date);        // "03-15-24"   (MM-DD-YY)
console.log(result.month);       // "March"
console.log(result.quarter);     // 1
console.log(result.year);        // "2024"
console.log(result.lastMonth);   // "February"
console.log(result.twoDigitDate); // "24"

All calls are silent by default (no stdout output). Pass silent: false to enable stdout output.

API Reference

getDate(options?)

import { getDate } from '@jhauga/getdate';
import type { GetDateOptions, GetDateResult } from '@jhauga/getdate';

const result: GetDateResult = getDate(options?: GetDateOptions);

Returns a plain GetDateResult object. The fields that are populated depend on which options you pass.

Options

| Option | Type | Description | |---|---|---| | day | boolean | Day of the month as two digits. Also sets date (MM-DD-YY). | | dayMonth | boolean | Two-digit month number. Only effective when day is also true. | | lastMonth | boolean | Full (or abbreviated) name of last month. | | lastQuarter | boolean | Independent. Last fiscal quarter (1–4). | | lastYear | boolean | Four-digit year of last year. | | month | boolean | Full (or abbreviated) name of the current month. | | nextYear | boolean | Independent. Four-digit year of next year. | | quarter | boolean | Current fiscal quarter (1–4), or season name when season: true. | | terminalDate | boolean | Independent. Date as MM/DD/YYYY (or reordered via order). | | year | boolean | Four-digit current year, or two-digit when twoDigit: true. | | full | boolean | Return MM-DD-YYYY (four-digit year) instead of MM-DD-YY. Result is in fullDate. | | slash | boolean | Use / as date separator instead of -. | | alternateVar | boolean | With slash, store the result in slashDate instead of date. | | customVar | string | With slash, store the result under this key on the returned object. | | leap | boolean | Independent. checkLeapYear: 1 if current year is a leap year, 0 otherwise. | | clearVars | boolean | Independent. Returns {} — signals that stored state should be cleared. | | silent | boolean | Unset or true suppresses stdout (the default). false writes output. | | abbreviated | boolean | Abbreviate month names ("Jan" vs "January"). Use with month or lastMonth. | | order | string | Token order for terminal date format. Use with terminalDate. E.g. "d-m-y", "y-m-d". | | twoDigit | boolean | Return only the last two digits of the year. Use with year. | | season | boolean | Return the season name instead of the quarter number. Use with quarter. |

Independent options short-circuit all other options when set: leap, terminalDate, lastQuarter, nextYear, clearVars.

Return Values

| Field | Type | Description | |---|---|---| | date | string | MM-DD-YY (default) or MM/DD/YY (with slash). | | fullDate | string | MM-DD-YYYY or MM/DD/YYYY (with full). | | slashDate | string | MM/DD/YY stored in the alternate slot (slash + alternateVar). | | twoDigitDate | string | YY — two-digit year (always set in default mode). | | lastMonth | string | Full or abbreviated name of last month. | | month | string | Full or abbreviated name of the current month. | | quarter | number \| string | Current fiscal quarter (1–4) or season name. | | lastQuarter | number | Last fiscal quarter (1–4). | | year | string | Four-digit (or two-digit) current year. | | lastYear | string | Four-digit last year. | | nextYear | string | Four-digit next year. | | day | string | Day of month as two digits. | | monthNumber | string | Month as two digits (set by dayMonth + day). | | terminalDate | string | Date in terminal format: MM/DD/YYYY or reordered. | | checkLeapYear | 0 \| 1 | 1 = leap year, 0 = not. | | [customVar] | string | Result stored under the key specified by customVar. |

Option Reference

Default call

const r = getDate();
// r.date        → "03-15-24"
// r.twoDigitDate → "24"
// r.lastMonth   → "February"
// r.month       → "March"
// r.quarter     → 1
// r.year        → "2024"

day — Day of month

const r = getDate({ day: true });
// r.day  → "15"
// r.date → "03-15-24"

day + dayMonth — Day and month number

const r = getDate({ day: true, dayMonth: true });
// r.day         → "15"
// r.monthNumber → "03"
// r.date        → "03-15-24"

lastMonth — Last month

getDate({ lastMonth: true }).lastMonth;         // "February"
getDate({ lastMonth: true, abbreviated: true }).lastMonth; // "Feb"

lastQuarter — Last quarter (independent)

// March 2024 → Q1 → last quarter = Q4
getDate({ lastQuarter: true }).lastQuarter;     // 4

lastYear — Last year

getDate({ lastYear: true }).lastYear;           // "2023"

month — Month name

getDate({ month: true }).month;                 // "March"
getDate({ month: true, abbreviated: true }).month; // "Mar"

nextYear — Next year (independent)

getDate({ nextYear: true }).nextYear;           // "2025"

quarter — Quarter

getDate({ quarter: true }).quarter;             // 1
getDate({ quarter: true, season: true }).quarter; // "Winter"

terminalDate — Terminal date (independent)

getDate({ terminalDate: true }).terminalDate;              // "03/15/2024"
getDate({ terminalDate: true, order: 'd-m-y' }).terminalDate; // "15/03/2024"
getDate({ terminalDate: true, order: 'y-m-d' }).terminalDate; // "2024/03/15"

year — Year

getDate({ year: true }).year;                   // "2024"
getDate({ year: true, twoDigit: true }).year;   // "24"

full — Four-digit year date

getDate({ full: true }).fullDate;               // "03-15-2024"

slash — Slash separator

getDate({ slash: true }).date;                           // "03/15/24"
getDate({ slash: true, alternateVar: true }).slashDate;  // "03/15/24"
getDate({ slash: true, customVar: '_myDate' })['_myDate']; // "03/15/24"

leap — Leap year check (independent)

getDate({ leap: true }).checkLeapYear;          // 1 (2024 is a leap year)

clearVars — Reset (independent)

getDate({ clearVars: true });                   // {}

Combinations

// month name, day, and full date
const r = getDate({ month: true, day: true });
// r.month → "March",  r.day → "15",  r.date → "03-15-24"

// month, quarter, year with output
const r = getDate({ month: true, quarter: true, year: true, silent: false });
// Writes "March, 1, 2024" to stdout
// r.month → "March",  r.quarter → 1,  r.year → "2024"

// last month, silent
const r = getDate({ lastMonth: true, silent: true });
// r.lastMonth → "February"  (no console output)

// four-digit year with slash separator
const r = getDate({ full: true, slash: true });
// r.fullDate → "03/15/2024"

Testing

The test suite covers:

• Unit tests — one test per option, verified against a fixed reference date
• Integration tests — combination scenarios, edge cases, cross-platform format checks

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Run with coverage report
npm run test:coverage

Tests require the dev dependencies to be installed:

npm install
npm test

Manual / User Test

A personal test file (tests/userTest.js) can be generated and run independently from the main test suite. It is git-ignored and not included when running npm test.

# Launch the interactive walkthrough to build tests/userTest.js
npm run test:make-user-test

# Run the generated test file
npm run test:user

test:make-user-test opens a terminal prompt where you:

1. Choose walkthrough (select options one at a time with arrow keys) or end process (generates a template with all options commented out).
2. In walkthrough mode, select each getDate option to add from a dropdown. After each selection you are asked "Add another line?" — answer with arrow keys, y, n, or Enter (Enter defaults to No).

Note: npm run test:user requires a build (npm run build) to be present. Run npm run build once before executing the user test.

Build

Compiles TypeScript source from src/ to JavaScript in dist/:

npm run build

Watch mode (rebuilds on file change):

npm run build:watch

Clean build output:

npm run clean

The compiled dist/ output includes:

• dist/index.js — CommonJS entry point
• dist/index.d.ts — TypeScript declarations
• dist/*.js.map — Source maps for debugging

License

MIT