format

Overview

The format object exposes methods for formatting numbers, dates and durations to be human-readable.

Methods and properties

Formatting automatically

String format(Number|Date value)

If value is a number, returns the value formatted with format.number(). Otherwise, returns the value formatted with format.date().
value
The value to format.
sample Format a number then a date
cli.tell(format(8.9)); // “8.90”
cli.tell(format(new Date('June 29, 2007 09:42'))); // “07-06-29 09:42:00”

Formatting numbers

String format.number(Number value, [String|Array unit, [Number decimalPlaces]])

Aliases format.number.float().

String format.number.float(Number value, [String|Array unit, [Number decimalPlaces]])

Returns value as a formatted string, adding thousands separators and enforcing the number of decimal places. If unit is specified, it is appended, and pluralized based on value.
value
The number to format.
unit
The unit to append to the formatted number. Can either be an array of two strings (the singular and plural form respectively) or a single string, to which an “s” will be appended to create the plural form.
Defaults to null.
decimalPlaces
The number of decimal places to include in the result. Zeroes are added to pad if necessary.
Defaults to 2.
sample Format with a string unit
cli.tell(format.number(1, 'carrot')); // “1.00 carrot”
cli.tell(format.number(4528.5, 'carrot')); // “4,528.50 carrots”
sample Format with an array unit
cli.tell(format.number(12.536, ['cactus', 'cacti'])); // “12.54 cacti”

String format.number.integer(Number value, [String|Array unit])

Returns value formatted with format.number.float() with the decimalPlaces argument set to 0.
value
The number to format.
unit
The unit to append to the formatted number. See format.number.float for details.
Defaults to null.
sample Format a number
cli.tell(format.number.integer(67.82, 'donut')); // “68 donuts”

Formatting dates

String format.date(Date|Moment value, [Boolean omitTime])

Aliases format.date.short().

String format.date.short(Date|Moment value, [Boolean omitTime])

Returns value as string, in YY-MM-DD HH:mm:ss format.
value
The date to format.
omitTime
Whether or not to leave out the time component of the date.
Defaults to false.
sample Format a date compactly
cli.tell(format.date.short(new Date('March 11, 1984, 8:30'))); // “84-03-11 08:30:00”

String format.date.long(Date|Moment value, [Boolean omitTime])

Returns value as a string, in WeekDayName, MonthName MonthDay, FullYear HH:mm:ss format.
value
The date to format.
omitTime
Whether or not to leave out the time component of the date.
Defaults to false.
sample Format a date explicitely
cli.tell(format.date.long(new Date('March 11, 1984, 8:30'))); // “Sunday, March 11th, 1984, 08:30:00”

String format.date.relative(Date|Moment value)

Returns the duration from the present date to value as a formatted string, such as "in 3 hours" or "10 days ago".
value
The date to format.
sample Format a modification date naturally
const logDate = here.file('log.txt').dateModified;
cli.tell(format.date.relative(logDate)); // “3 minutes ago”

Formatting durations

String format.duration(Date|Moment date1, Date|Moment date2)

Aliases format.duration.between().

String format.duration.between(Date|Moment date1, Date|Moment date2)

Returns the duration between date1 and date2 as a formatted string.
date1
The start of the duration.
date2
The end of the duration.
sample Report execution time
const startDate = new Date();
performSlowOperation();
const endDate = new Date();

cli.tell(format.duration(startDate, endDate)); // “32 minutes”
cli methods such as cli.tell() are a natural place to use nicely formatted values.