Temporal.PlainTime.prototype.since()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The since() method of Temporal.PlainTime instances returns a new Temporal.Duration object representing the duration from another time (in a form convertible by Temporal.PlainTime.from()) to this time. The duration is positive if the other time is before this time, and negative if after.

This method does this - other. To do other - this, use the until() method.

Syntax

since(other)
since(other, options)

Parameters

other: A string, an object, or a Temporal.PlainTime instance representing a time to subtract from this time. It is converted to a Temporal.PlainTime object using the same algorithm as Temporal.PlainTime.from().
options Optional: An object containing the options for Temporal.Duration.prototype.round(), which includes largestUnit, roundingIncrement, roundingMode, and smallestUnit. largestUnit and smallestUnit only accept the units: "hour", "minute", "second", "millisecond", "microsecond", "nanosecond", or their plural forms. For largestUnit, the default value "auto" means "hour". For smallestUnit, the default value is "nanosecond".

Return value

A new Temporal.Duration object representing the duration since other to this time. The duration is positive if other is before this time, and negative if after.

Exceptions

RangeError: Thrown if any of the options is invalid.

Examples

Using since()

const lunchTime = Temporal.PlainTime.from("12:30:00");
const now = Temporal.Now.plainTimeISO();
const duration = now.since(lunchTime);
console.log(`You had lunch ${duration.toLocaleString("en-US")} ago`);
// Example output: "You had lunch 3 hr, 42 min, 21 sec, 343 ms, 131 μs, 718 ns ago"

const duration2 = now.since(lunchTime, { smallestUnit: "minute" });
console.log(`You had lunch ${duration2.toLocaleString("en-US")} ago`);
// Example output: "You had lunch 3 hr, 42 min ago"

const duration3 = now.since(lunchTime, {
  largestUnit: "minute",
  smallestUnit: "minute",
});
console.log(`You had lunch ${duration3.toLocaleString("en-US")} ago`);
// Example output: "You had lunch 222 min ago"

Rounding the result

By default the fractional part of the smallestUnit is truncated. You can round it up using the roundingIncrement and roundingMode options.

const time1 = Temporal.PlainTime.from("12:30:00");
const time2 = Temporal.PlainTime.from("12:30:01");
const duration = time2.since(time1, {
  smallestUnit: "second",
  roundingIncrement: 15,
  roundingMode: "ceil",
});
console.log(duration.toString()); // "PT15S"

Specifications

Specification
Temporal proposal # sec-temporal.plaintime.prototype.since

Browser compatibility

	Desktop					Mobile						Server
	Chrome	Edge	Firefox	Opera	Safari	Chrome Android	Firefox for Android	Opera Android	Safari on IOS	Samsung Internet	WebView Android	Deno	Node.js
`since`	No	No	No	No	preview	No	No	No	No	No	No	1.40	No