Get Timestamp

getTimestamp

Generates an ISO 8601 timestamp string from a date input, or from the current time when no input is provided.

Function Signatures

getTimestamp(): ISOTimeString;
getTimestamp(value: DateArgs, format?: ISODateFormat): ISOTimeString;
getTimestamp(options?: TimestampOptions): ISOTimeString;

Parameters

Name	Type	Description
value	DateArgs	Date input as a Date, date string, or timestamp number.
format	ISODateFormat	Output format: 'utc' (default) or 'local'.
options	TimestampOptions	Object containing optional value and format.

Returns

ISOTimeString - An ISO 8601 timestamp string.

If format is 'utc', the output ends with Z. If format is 'local', the output includes the local time & timezone offset like +06:00.

Example Usage

Overload: No Arguments

import { getTimestamp } from 'nhb-toolbox';

const ts = getTimestamp();
console.log(ts); // "2025-04-06T16:11:55.000Z" (example)

Overload: Value and Format

import { getTimestamp } from 'nhb-toolbox';

const tsUtc = getTimestamp(new Date(2025, 3, 6, 16, 11, 55), 'utc');
const tsLocal = getTimestamp(new Date(2025, 3, 6, 16, 11, 55), 'local');

console.log(tsUtc);   // "2025-04-06T16:11:55.000Z"
console.log(tsLocal); // "2025-04-06T22:11:55.000+05:30" (time + offset varies)

Overload: Options Object

import { getTimestamp } from 'nhb-toolbox';

const ts1 = getTimestamp({ value: 1712748715000, format: 'utc' });
const ts2 = getTimestamp({ format: 'local' });

console.log(ts1); // "2024-04-10T11:31:55.000Z"
console.log(ts2); // "2025-04-06T16:11:55.000+05:30" (example, offset varies)

Notes

• Defaults to the current date and time when no value is provided.
• Invalid date input falls back to the current date and time.
• 'local' output reflects the system timezone offset for the given date.
• 'utc' output matches Date.prototype.toISOString() for valid inputs.
• The output is always a string typed as ISOTimeString for type safety and clarity in codebases.
• The output value (whether UTC or local) is always in ISO 8601 format and returns the same instance of Date when used as new Date(getTimestamp(some-value)) for valid inputs, ensuring consistency across formats.
• Exported as getTimestamp (lowercase s), separate from Chronos.getTimeStamp() which returns timestamp in milliseconds.

Type Definitions

type DateArgs = string | number | Date;
type ISODateFormat = 'local' | 'utc';

interface TimestampOptions {
  value?: DateArgs;
  format?: ISODateFormat;
}

type ISOTimeString = `${number}-${number}-${number}T${number}:${number}:${number}.${number}${'Z' | $UTCOffset}`;

Use Cases

• Storing timestamps in logs and databases
• Generating ISO strings for APIs
• Converting inputs to a consistent timestamp format
• Including local timezone offsets for display or auditing

Conclusion

The getTimestamp utility provides:

1. Simple ISO output with minimal configuration
2. Flexible inputs via Date, string, or numeric timestamp
3. UTC or local formatting depending on your needs
4. Safe defaults for invalid or missing inputs

Ideal for applications requiring:

• Consistent timestamp formatting
• Quick conversion of date inputs
• UTC-first data storage
• Local time presentation with offset