Get Timestamp

getTimestamp

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

Import

import { getTimestamp } from "toolbox-x/utils";

Function Signatures

getTimestamp(): ISODateTimeString<'utc'>;
getTimestamp(value: DateArgs, format?: ISODateFormat): ISODateTimeString<'utc' | 'local'>;
getTimestamp(options?: TimestampOptions): ISODateTimeString<'utc' | 'local'>;

Parameters

Returns

ISODateTimeString<'utc'> (default) or ISODateTimeString<'local'> - 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

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 ISODateTimeString<'utc'> or ISODateTimeString<'local'> 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}`;

type ISODateTimeString<F extends ISODateFormat = 'utc'> = F extends 'utc'
	? `${$ISOTimeString}Z`
	: `${$ISOTimeString}${$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