luxon
Version:
Immutable date wrapper
744 lines (669 loc) • 23.3 kB
JavaScript
import { isUndefined, isNumber, normalizeObject } from './impl/util';
import Locale from './impl/locale';
import Formatter from './impl/formatter';
import { parseISODuration } from './impl/regexParser';
import Settings from './settings';
import { InvalidArgumentError, InvalidDurationError, InvalidUnitError } from './errors';
const INVALID = 'Invalid Duration',
UNPARSABLE = 'unparsable';
// unit conversion constants
const lowOrderMatrix = {
weeks: {
days: 7,
hours: 7 * 24,
minutes: 7 * 24 * 60,
seconds: 7 * 24 * 60 * 60,
milliseconds: 7 * 24 * 60 * 60 * 1000
},
days: {
hours: 24,
minutes: 24 * 60,
seconds: 24 * 60 * 60,
milliseconds: 24 * 60 * 60 * 1000
},
hours: { minutes: 60, seconds: 60 * 60, milliseconds: 60 * 60 * 1000 },
minutes: { seconds: 60, milliseconds: 60 * 1000 },
seconds: { milliseconds: 1000 }
},
casualMatrix = Object.assign(
{
years: {
months: 12,
weeks: 52,
days: 365,
hours: 365 * 24,
minutes: 365 * 24 * 60,
seconds: 365 * 24 * 60 * 60,
milliseconds: 365 * 24 * 60 * 60 * 1000
},
quarters: {
months: 3,
weeks: 13,
days: 91,
hours: 91 * 24,
minutes: 91 * 24 * 60,
milliseconds: 91 * 24 * 60 * 60 * 1000
},
months: {
weeks: 4,
days: 30,
hours: 30 * 24,
minutes: 30 * 24 * 60,
seconds: 30 * 24 * 60 * 60,
milliseconds: 30 * 24 * 60 * 60 * 1000
}
},
lowOrderMatrix
),
daysInYearAccurate = 146097.0 / 400,
daysInMonthAccurate = 146097.0 / 4800,
accurateMatrix = Object.assign(
{
years: {
months: 12,
weeks: daysInYearAccurate / 7,
days: daysInYearAccurate,
hours: daysInYearAccurate * 24,
minutes: daysInYearAccurate * 24 * 60,
seconds: daysInYearAccurate * 24 * 60 * 60,
milliseconds: daysInYearAccurate * 24 * 60 * 60 * 1000
},
quarters: {
months: 3,
weeks: daysInYearAccurate / 28,
days: daysInYearAccurate / 4,
hours: daysInYearAccurate * 24 / 4,
minutes: daysInYearAccurate * 24 * 60 / 4,
seconds: daysInYearAccurate * 24 * 60 * 60 / 4,
milliseconds: daysInYearAccurate * 24 * 60 * 60 * 1000 / 4
},
months: {
weeks: daysInMonthAccurate / 7,
days: daysInMonthAccurate,
hours: daysInMonthAccurate * 24,
minutes: daysInMonthAccurate * 24 * 60,
seconds: daysInMonthAccurate * 24 * 60 * 60,
milliseconds: daysInMonthAccurate * 24 * 60 * 60 * 1000
}
},
lowOrderMatrix
);
// units ordered by size
const orderedUnits = [
'years',
'quarters',
'months',
'weeks',
'days',
'hours',
'minutes',
'seconds',
'milliseconds'
];
const reverseUnits = orderedUnits.slice(0).reverse();
// clone really means "create another instance just like this one, but with these changes"
function clone(dur, alts, clear = false) {
// deep merge for vals
const conf = {
values: clear ? alts.values : Object.assign({}, dur.values, alts.values || {}),
loc: dur.loc.clone(alts.loc),
conversionAccuracy: alts.conversionAccuracy || dur.conversionAccuracy
};
return new Duration(conf);
}
// some functions really care about the absolute value of a duration, so combined with
// normalize() this tells us whether this duration is positive or negative
function isHighOrderNegative(obj) {
// only rule is that the highest-order part must be non-negative
for (const k of orderedUnits) {
if (obj[k]) return obj[k] < 0;
}
return false;
}
// NB: mutates parameters
function convert(matrix, fromMap, fromUnit, toMap, toUnit) {
const conv = matrix[toUnit][fromUnit],
added = Math.floor(fromMap[fromUnit] / conv);
toMap[toUnit] += added;
fromMap[fromUnit] -= added * conv;
}
// NB: mutates parameters
function normalizeValues(matrix, vals) {
reverseUnits.reduce((previous, current) => {
if (!isUndefined(vals[current])) {
if (previous) {
convert(matrix, vals, previous, vals, current);
}
return current;
} else {
return previous;
}
}, null);
}
/**
* @private
*/
export function friendlyDuration(duration) {
if (isNumber(duration)) {
return Duration.fromMillis(duration);
} else if (duration instanceof Duration) {
return duration;
} else if (duration instanceof Object) {
return Duration.fromObject(duration);
} else {
throw new InvalidArgumentError('Unknown duration argument');
}
}
/**
* A Duration object represents a period of time, like "2 months" or "1 day, 1 hour". Conceptually, it's just a map of units to their quantities, accompanied by some additional configuration and methods for creating, parsing, interrogating, transforming, and formatting them. They can be used on their own or in conjunction with other Luxon types; for example, you can use {@link DateTime.plus} to add a Duration object to a DateTime, producing another DateTime.
*
* Here is a brief overview of commonly used methods and getters in Duration:
*
* * **Creation** To create a Duration, use {@link Duration.fromMillis}, {@link Duration.fromObject}, or {@link Duration.fromISO}.
* * **Unit values** See the {@link years}, {@link months}, {@link weeks}, {@link days}, {@link hours}, {@link minutes}, {@link seconds}, {@link milliseconds} accessors.
* * **Configuration** See {@link locale} and {@link numberingSystem} accessors.
* * **Transformation** To create new Durations out of old ones use {@link plus}, {@link minus}, {@link normalize}, {@link set}, {@link reconfigure}, {@link shiftTo}, and {@link negate}.
* * **Output** To convert the Duration into other representations, see {@link as}, {@link toISO}, {@link toFormat}, and {@link toJSON}
*
* There's are more methods documented below. In addition, for more information on subtler topics like internationalization and validity, see the external documentation.
*/
export default class Duration {
/**
* @private
*/
constructor(config) {
const accurate = config.conversionAccuracy === 'longterm' || false;
/**
* @access private
*/
this.values = config.values;
/**
* @access private
*/
this.loc = config.loc || Locale.create();
/**
* @access private
*/
this.conversionAccuracy = accurate ? 'longterm' : 'casual';
/**
* @access private
*/
this.invalid = config.invalidReason || null;
/**
* @access private
*/
this.matrix = accurate ? accurateMatrix : casualMatrix;
}
/**
* Create Duration from a number of milliseconds.
* @param {number} count of milliseconds
* @param {Object} opts - options for parsing
* @param {string} [opts.locale='en-US'] - the locale to use
* @param {string} opts.numberingSystem - the numbering system to use
* @param {string} [opts.conversionAccuracy='casual'] - the conversion system to use
* @return {Duration}
*/
static fromMillis(count, opts) {
return Duration.fromObject(Object.assign({ milliseconds: count }, opts));
}
/**
* Create a Duration from a Javascript object with keys like 'years' and 'hours.
* If this object is empty then zero milliseconds duration is returned.
* @param {Object} obj - the object to create the DateTime from
* @param {number} obj.years
* @param {number} obj.quarters
* @param {number} obj.months
* @param {number} obj.weeks
* @param {number} obj.days
* @param {number} obj.hours
* @param {number} obj.minutes
* @param {number} obj.seconds
* @param {number} obj.milliseconds
* @param {string} [obj.locale='en-US'] - the locale to use
* @param {string} obj.numberingSystem - the numbering system to use
* @param {string} [obj.conversionAccuracy='casual'] - the conversion system to use
* @return {Duration}
*/
static fromObject(obj) {
if (obj == null || typeof obj !== 'object') {
throw new InvalidArgumentError(
'Duration.fromObject: argument expected to be an object.'
);
}
return new Duration({
values: normalizeObject(obj, Duration.normalizeUnit, true),
loc: Locale.fromObject(obj),
conversionAccuracy: obj.conversionAccuracy
});
}
/**
* Create a Duration from an ISO 8601 duration string.
* @param {string} text - text to parse
* @param {Object} opts - options for parsing
* @param {string} [opts.locale='en-US'] - the locale to use
* @param {string} opts.numberingSystem - the numbering system to use
* @param {string} [opts.conversionAccuracy='casual'] - the conversion system to use
* @see https://en.wikipedia.org/wiki/ISO_8601#Durations
* @example Duration.fromISO('P3Y6M4DT12H30M5S').toObject() //=> { years: 3, months: 6, day: 4, hours: 12, minutes: 30, seconds: 5 }
* @example Duration.fromISO('PT23H').toObject() //=> { hours: 23 }
* @example Duration.fromISO('P5Y3M').toObject() //=> { years: 5, months: 3 }
* @return {Duration}
*/
static fromISO(text, opts) {
const [parsed] = parseISODuration(text);
if (parsed) {
const obj = Object.assign(parsed, opts);
return Duration.fromObject(obj);
} else {
return Duration.invalid(UNPARSABLE);
}
}
/**
* Create an invalid Duration.
* @param {string} reason - reason this is invalid
* @return {Duration}
*/
static invalid(reason) {
if (!reason) {
throw new InvalidArgumentError('need to specify a reason the Duration is invalid');
}
if (Settings.throwOnInvalid) {
throw new InvalidDurationError(reason);
} else {
return new Duration({ invalidReason: reason });
}
}
/**
* @private
*/
static normalizeUnit(unit, ignoreUnknown = false) {
const normalized = {
year: 'years',
years: 'years',
quarter: 'quarters',
quarters: 'quarters',
month: 'months',
months: 'months',
week: 'weeks',
weeks: 'weeks',
day: 'days',
days: 'days',
hour: 'hours',
hours: 'hours',
minute: 'minutes',
minutes: 'minutes',
second: 'seconds',
seconds: 'seconds',
millisecond: 'milliseconds',
milliseconds: 'milliseconds'
}[unit ? unit.toLowerCase() : unit];
if (!ignoreUnknown && !normalized) throw new InvalidUnitError(unit);
return normalized;
}
/**
* Get the locale of a Duration, such 'en-GB'
* @type {string}
*/
get locale() {
return this.isValid ? this.loc.locale : null;
}
/**
* Get the numbering system of a Duration, such 'beng'. The numbering system is used when formatting the Duration
*
* @type {string}
*/
get numberingSystem() {
return this.isValid ? this.loc.numberingSystem : null;
}
/**
* Returns a string representation of this Duration formatted according to the specified format string.
* @param {string} fmt - the format string
* @param {Object} opts - options
* @param {boolean} [opts.floor=true] - floor numerical values
* @return {string}
*/
toFormat(fmt, opts = {}) {
// reverse-compat since 1.2; we always round down now, never up, and we do it by default. So:
// 1. always turn off rounding in the underlying formatter
// 2. turn off flooring if either rounding is turned off or flooring is turned off, otherwise leave it on
const fmtOpts = Object.assign({}, opts, { floor: true, round: false });
if (opts.round === false || opts.floor === false) {
fmtOpts.floor = false;
}
return this.isValid
? Formatter.create(this.loc, fmtOpts).formatDurationFromString(this, fmt)
: INVALID;
}
/**
* Returns a Javascript object with this Duration's values.
* @param opts - options for generating the object
* @param {boolean} [opts.includeConfig=false] - include configuration attributes in the output
* @example Duration.fromObject({ years: 1, days: 6, seconds: 2 }).toObject() //=> { years: 1, days: 6, seconds: 2 }
* @return {Object}
*/
toObject(opts = {}) {
if (!this.isValid) return {};
const base = Object.assign({}, this.values);
if (opts.includeConfig) {
base.conversionAccuracy = this.conversionAccuracy;
base.numberingSystem = this.loc.numberingSystem;
base.locale = this.loc.locale;
}
return base;
}
/**
* Returns an ISO 8601-compliant string representation of this Duration.
* @see https://en.wikipedia.org/wiki/ISO_8601#Durations
* @example Duration.fromObject({ years: 3, seconds: 45 }).toISO() //=> 'P3YT45S'
* @example Duration.fromObject({ months: 4, seconds: 45 }).toISO() //=> 'P4MT45S'
* @example Duration.fromObject({ months: 5 }).toISO() //=> 'P5M'
* @example Duration.fromObject({ minutes: 5 }).toISO() //=> 'PT5M'
* @return {string}
*/
toISO() {
// we could use the formatter, but this is an easier way to get the minimum string
if (!this.isValid) return null;
let s = 'P',
norm = this.normalize();
// ISO durations are always positive, so take the absolute value
norm = isHighOrderNegative(norm.values) ? norm.negate() : norm;
if (norm.years > 0) s += norm.years + 'Y';
if (norm.months > 0 || norm.quarters > 0) s += norm.months + norm.quarters * 3 + 'M';
if (norm.days > 0 || norm.weeks > 0) s += norm.days + norm.weeks * 7 + 'D';
if (norm.hours > 0 || norm.minutes > 0 || norm.seconds > 0 || norm.milliseconds > 0) s += 'T';
if (norm.hours > 0) s += norm.hours + 'H';
if (norm.minutes > 0) s += norm.minutes + 'M';
if (norm.seconds > 0) s += norm.seconds + 'S';
return s;
}
/**
* Returns an ISO 8601 representation of this Duration appropriate for use in JSON.
* @return {string}
*/
toJSON() {
return this.toISO();
}
/**
* Returns an ISO 8601 representation of this Duration appropriate for use in debugging.
* @return {string}
*/
toString() {
return this.toISO();
}
/**
* Returns an milliseconds value of this Duration.
* @return {number}
*/
valueOf() {
return this.as('milliseconds');
}
/**
* Returns a string representation of this Duration appropriate for the REPL.
* @return {string}
*/
inspect() {
if (this.isValid) {
const valsInspect = JSON.stringify(this.toObject());
return `Duration {\n values: ${valsInspect},\n locale: ${this
.locale},\n conversionAccuracy: ${this.conversionAccuracy} }`;
} else {
return `Duration { Invalid, reason: ${this.invalidReason} }`;
}
}
/**
* Make this Duration longer by the specified amount. Return a newly-constructed Duration.
* @param {Duration|Object|number} duration - The amount to add. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()
* @return {Duration}
*/
plus(duration) {
if (!this.isValid) return this;
const dur = friendlyDuration(duration),
result = {};
for (const k of orderedUnits) {
const val = dur.get(k) + this.get(k);
if (val !== 0) {
result[k] = val;
}
}
return clone(this, { values: result }, true);
}
/**
* Make this Duration shorter by the specified amount. Return a newly-constructed Duration.
* @param {Duration|Object|number} duration - The amount to subtract. Either a Luxon Duration, a number of milliseconds, the object argument to Duration.fromObject()
* @return {Duration}
*/
minus(duration) {
if (!this.isValid) return this;
const dur = friendlyDuration(duration);
return this.plus(dur.negate());
}
/**
* Get the value of unit.
* @param {string} unit - a unit such as 'minute' or 'day'
* @example Duration.fromObject({years: 2, days: 3}).years //=> 2
* @example Duration.fromObject({years: 2, days: 3}).months //=> 0
* @example Duration.fromObject({years: 2, days: 3}).days //=> 3
* @return {number}
*/
get(unit) {
return this[Duration.normalizeUnit(unit)];
}
/**
* "Set" the values of specified units. Return a newly-constructed Duration.
* @param {Object} values - a mapping of units to numbers
* @example dur.set({ years: 2017 })
* @example dur.set({ hours: 8, minutes: 30 })
* @return {Duration}
*/
set(values) {
const mixed = Object.assign(this.values, normalizeObject(values, Duration.normalizeUnit));
return clone(this, { values: mixed });
}
/**
* "Set" the locale and/or numberingSystem. Returns a newly-constructed Duration.
* @example dur.reconfigure({ locale: 'en-GB' })
* @return {Duration}
*/
reconfigure({ locale, numberingSystem, conversionAccuracy } = {}) {
const loc = this.loc.clone({ locale, numberingSystem }),
opts = { loc };
if (conversionAccuracy) {
opts.conversionAccuracy = conversionAccuracy;
}
return clone(this, opts);
}
/**
* Return the length of the duration in the specified unit.
* @param {string} unit - a unit such as 'minutes' or 'days'
* @example Duration.fromObject({years: 1}).as('days') //=> 365
* @example Duration.fromObject({years: 1}).as('months') //=> 12
* @example Duration.fromObject({hours: 60}).as('days') //=> 2.5
* @return {number}
*/
as(unit) {
return this.isValid ? this.shiftTo(unit).get(unit) : NaN;
}
/**
* Reduce this Duration to its canonical representation in its current units.
* @example Duration.fromObject({ years: 2, days: 5000 }).normalize().toObject() //=> { years: 15, days: 255 }
* @example Duration.fromObject({ hours: 12, minutes: -45 }).normalize().toObject() //=> { hours: 11, minutes: 15 }
* @return {Duration}
*/
normalize() {
if (!this.isValid) return this;
const neg = isHighOrderNegative(this.values),
vals = (neg ? this.negate() : this).toObject();
normalizeValues(this.matrix, vals);
const dur = Duration.fromObject(vals);
return neg ? dur.negate() : dur;
}
/**
* Convert this Duration into its representation in a different set of units.
* @example Duration.fromObject({ hours: 1, seconds: 30 }).shiftTo('minutes', 'milliseconds').toObject() //=> { minutes: 60, milliseconds: 30000 }
* @return {Duration}
*/
shiftTo(...units) {
if (!this.isValid) return this;
if (units.length === 0) {
return this;
}
units = units.map(u => Duration.normalizeUnit(u));
const built = {},
accumulated = {},
vals = this.toObject();
let lastUnit;
normalizeValues(this.matrix, vals);
for (const k of orderedUnits) {
if (units.indexOf(k) >= 0) {
lastUnit = k;
let own = 0;
// anything we haven't boiled down yet should get boiled to this unit
for (const ak in accumulated) {
if (accumulated.hasOwnProperty(ak)) {
own += this.matrix[ak][k] * accumulated[ak];
accumulated[ak] = 0;
}
}
// plus anything that's already in this unit
if (isNumber(vals[k])) {
own += vals[k];
}
const i = Math.trunc(own);
built[k] = i;
accumulated[k] = own - i;
// plus anything further down the chain that should be rolled up in to this
for (const down in vals) {
if (orderedUnits.indexOf(down) > orderedUnits.indexOf(k)) {
convert(this.matrix, vals, down, built, k);
}
}
// otherwise, keep it in the wings to boil it later
} else if (isNumber(vals[k])) {
accumulated[k] = vals[k];
}
}
// anything leftover becomes the decimal for the last unit
if (lastUnit) {
for (const key in accumulated) {
if (accumulated.hasOwnProperty(key)) {
if (accumulated[key] > 0) {
built[lastUnit] +=
key === lastUnit ? accumulated[key] : accumulated[key] / this.matrix[lastUnit][key];
}
}
}
}
return clone(this, { values: built }, true);
}
/**
* Return the negative of this Duration.
* @example Duration.fromObject({ hours: 1, seconds: 30 }).negate().toObject() //=> { hours: -1, seconds: -30 }
* @return {Duration}
*/
negate() {
if (!this.isValid) return this;
const negated = {};
for (const k of Object.keys(this.values)) {
negated[k] = -this.values[k];
}
return clone(this, { values: negated }, true);
}
/**
* Get the years.
* @type {number}
*/
get years() {
return this.isValid ? this.values.years || 0 : NaN;
}
/**
* Get the quarters.
* @type {number}
*/
get quarters() {
return this.isValid ? this.values.quarters || 0 : NaN;
}
/**
* Get the months.
* @type {number}
*/
get months() {
return this.isValid ? this.values.months || 0 : NaN;
}
/**
* Get the weeks
* @type {number}
*/
get weeks() {
return this.isValid ? this.values.weeks || 0 : NaN;
}
/**
* Get the days.
* @type {number}
*/
get days() {
return this.isValid ? this.values.days || 0 : NaN;
}
/**
* Get the hours.
* @type {number}
*/
get hours() {
return this.isValid ? this.values.hours || 0 : NaN;
}
/**
* Get the minutes.
* @type {number}
*/
get minutes() {
return this.isValid ? this.values.minutes || 0 : NaN;
}
/**
* Get the seconds.
* @return {number}
*/
get seconds() {
return this.isValid ? this.values.seconds || 0 : NaN;
}
/**
* Get the milliseconds.
* @return {number}
*/
get milliseconds() {
return this.isValid ? this.values.milliseconds || 0 : NaN;
}
/**
* Returns whether the Duration is invalid. Invalid durations are returned by diff operations
* on invalid DateTimes or Intervals.
* @return {boolean}
*/
get isValid() {
return this.invalidReason === null;
}
/**
* Returns an explanation of why this Duration became invalid, or null if the Duration is valid
* @return {string}
*/
get invalidReason() {
return this.invalid;
}
/**
* Equality check
* Two Durations are equal iff they have the same units and the same values for each unit.
* @param {Duration} other
* @return {boolean}
*/
equals(other) {
if (!this.isValid || !other.isValid) {
return false;
}
if (!this.loc.equals(other.loc)) {
return false;
}
for (const u of orderedUnits) {
if (this.values[u] !== other.values[u]) {
return false;
}
}
return true;
}
}