@js-joda/core 1.12.0 → 3.2.0

package/src/temporal/Temporal.js

@@ -5,6 +5,7 @@
  */
 
 import {TemporalAccessor} from './TemporalAccessor';
+import { abstractMethodFail } from '../assert';
 
 /**
  * Framework-level interface defining read-write access to a temporal object,
@@ -60,4 +61,286 @@ import {TemporalAccessor} from './TemporalAccessor';
  *
  * @interface
  */
-export class Temporal extends TemporalAccessor {}
+export class Temporal extends TemporalAccessor {
+    /**
+     * Checks if the specified unit is supported.
+     * This checks if the date-time can be queried for the specified unit. If false, then calling the plus and minus methods will throw an exception.
+
+     * ### Specification for implementors
+     * Implementations must check and handle all fields defined in {@link ChronoUnit}. If the field is supported, then true is returned, otherwise false
+     * If the field is not a {@link ChronoUnit}, then the result of this method is obtained by invoking `TemporalUnit.isSupportedBy(Temporal)` passing this as the argument.
+
+     * Implementations must not alter this object.
+
+     * @param {TemporalUnit} unit - the unit to check, null returns false
+     * @return {boolean} true if this date-time can be queried for the unit, false if not
+     */
+    // eslint-disable-next-line no-unused-vars
+    isSupported(unit) {
+        abstractMethodFail('isSupported');
+    }
+
+    /**
+     * function overloading for {@link Temporal.plus}
+     *
+     * Called with 1 (or less) arguments, p1 is expected to be a {@link TemporalAmount} and {@link Temporal.minusAmount} is called.
+     *
+     * Otherwise {@link Temporal.minusAmountUnit} is called.
+     *
+     * @param {!(TemporalAmount|number)} p1
+     * @param {TemporalUnit} p2
+     * @return {Temporal}
+     */
+    // eslint-disable-next-line no-unused-vars
+    minus(p1, p2) {
+        if (arguments.length < 2) {
+            return this.minusAmount(p1);
+        } else {
+            return this.minusAmountUnit(p1, p2);
+        }
+    }
+
+    /**
+     * Returns an object of the same type as this object with an amount subtracted.
+     * This adjusts this temporal, subtracting according to the rules of the specified amount. The
+     * amount is typically a {@link Period} but may be any other type implementing the {@link TemporalAmount} interface, such as Duration.
+     *
+     * Some example code indicating how and why this method is used:
+     *
+     * <pre>
+     *   date = date.minus(period);                  // subtract a Period instance
+     *   date = date.minus(duration);                // subtract a Duration instance
+     *   date = date.minus(workingDays(6));          // example user-written workingDays method
+     * </pre>
+     *
+     * Note that calling plus followed by minus is not guaranteed to return the same date-time.
+     *
+     * ### Specification for implementors
+     * Implementations must not alter either this object. Instead, an adjusted copy of the original
+     * must be returned. This provides equivalent, safe behavior for immutable and mutable
+     * implementations.
+     *
+     * @param {TemporalAmount} amount - the amount to subtract, not null
+     * @return {Temporal} an object of the same type with the specified adjustment made, not null
+     * @throws DateTimeException - if the subtraction cannot be made
+     * @throws ArithmeticException - if numeric overflow occurs
+     */
+    // eslint-disable-next-line no-unused-vars
+    minusAmount(amount) {
+        abstractMethodFail('minusAmount');
+    }
+
+    /**
+     * Returns an object of the same type as this object with the specified period subtracted.
+     * This method returns a new object based on this one with the specified period subtracted. For example, on a {@link LocalDate}, this could be used to subtract a number of years, months or days. The returned object will have the same observable type as this object.
+     *
+     * In some cases, changing a field is not fully defined. For example, if the target object is a date representing the 31st March, then subtracting one month would be unclear. In cases like this, the field is responsible for resolving the result. Typically it will choose the previous valid date, which would be the last valid day of February in this example.
+     *
+     * If the implementation represents a date-time that has boundaries, such {@link as} LocalTime, then the permitted units must include the boundary unit, but no multiples of the boundary unit. For example, {@link LocalTime} must accept `DAYS` but not `WEEKS` or `MONTHS`.
+     *
+     * ### Specification for implementors
+     * Implementations must behave in a manor equivalent to the default method behavior.
+     * Implementations must not alter either this object or the specified temporal object. Instead, an adjusted copy of the original must be returned. This provides equivalent, safe behavior for immutable and mutable implementations.
+     *
+     * @param {number} amountToSubtract - the amount of the specified unit to subtract, may be negative
+     * @param {TemporalUnit} unit - the unit of the period to subtract, not null
+     * @return {Temporal} an object of the same type with the specified period subtracted, not null
+     * @throws DateTimeException - if the unit cannot be subtracted
+     * @throws ArithmeticException - if numeric overflow occurs
+     */
+    // eslint-disable-next-line no-unused-vars
+    minusAmountUnit(amountToSubtract, unit) {
+        abstractMethodFail('minusAmountUnit');
+    }
+
+    /**
+     * function overloading for {@link Temporal.plus}
+     *
+     * Called with 1 (or less) arguments, p1 is expected to be a {@link TemporalAmount} and {@link Temporal.plusAmount} is called.
+     *
+     * Otherwise {@link Temporal.plusAmountUnit} is called.
+     *
+     * @param {!(TemporalAmount|number)} p1
+     * @param {TemporalUnit} p2
+     * @return {Temporal}
+     */
+    // eslint-disable-next-line no-unused-vars
+    plus(p1, p2) {
+        if (arguments.length < 2) {
+            return this.plusAmount(p1);
+        } else {
+            return this.plusAmountUnit(p1, p2);
+        }
+    }
+
+    /**
+     * Returns an object of the same type as this object with an amount added.
+     * This adjusts this temporal, adding according to the rules of the specified amount. The amount is typically a {@link Period} but may be any other type implementing the {@link TemporalAmount} interface, such as {@link Duration}.
+     *
+     * Some example code indicating how and why this method is used:
+     *
+     * <pre>
+     *   date = date.plus(period);                  // add a Period instance
+     *   date = date.plus(duration);                // add a Duration instance
+     *   date = date.plus(workingDays(6));          // example user-written workingDays method
+     * </pre>
+     *
+     * Note that calling plus followed by minus is not guaranteed to return the same date-time.
+     *
+     * ### Specification for implementors
+     * Implementations must not alter either this object. Instead, an adjusted copy of the original must be returned. This provides equivalent, safe behavior for immutable and mutable implementations.
+     *
+     * @param {TemporalAmount} amount - the amount to add, not null
+     * @return {Temporal} an object of the same type with the specified adjustment made, not null
+     * @throws DateTimeException - if the addition cannot be made
+     * @throws ArithmeticException - if numeric overflow occurs
+     */
+    // eslint-disable-next-line no-unused-vars
+    plusAmount(amount) {
+        abstractMethodFail('plusAmount');
+    }
+
+    /**
+     * Returns an object of the same type as this object with the specified period added.
+     * This method returns a new object based on this one with the specified period added. For example, on a {@link LocalDate}, this could be used to add a number of years, months or days. The returned object will have the same observable type as this object.
+     *
+     * In some cases, changing a field is not fully defined. For example, if the target object is a date representing the 31st January, then adding one month would be unclear. In cases like this, the field is responsible for resolving the result. Typically it will choose the previous valid date, which would be the last valid day of February in this example.
+     *
+     * If the implementation represents a date-time that has boundaries, such as {@link LocalTime}, then the permitted units must include the boundary unit, but no multiples of the boundary unit. For example, {@link LocalTime} must accept `DAYS` but not `WEEKS` or `MONTHS`.
+     *
+     * ### Specification for implementors
+     * Implementations must check and handle all units defined in {@link ChronoUnit}. If the unit is supported, then the addition must be performed. If unsupported, then a {@link DateTimeException} must be thrown.
+     * If the unit is not a {@link ChronoUnit}, then the result of this method is obtained by invoking `TemporalUnit.addTo(Temporal, long)` passing this as the first argument.
+     *
+     * Implementations must not alter either this object or the specified temporal object. Instead, an adjusted copy of the original must be returned. This provides equivalent, safe behavior for immutable and mutable implementations.
+     *
+     * @param {number} amountToAdd - the amount of the specified unit to add, may be negative
+     * @param {TemporalUnit} unit - the unit of the period to add, not null
+     * @return {Temporal} an object of the same type with the specified period added, not null
+     * @throws DateTimeException - if the unit cannot be added
+     * @throws ArithmeticException - if numeric overflow occurs
+     */
+    // eslint-disable-next-line no-unused-vars
+    plusAmountUnit(amountToAdd, unit) {
+        abstractMethodFail('plusAmountUnit');
+    }
+
+    /**
+     * Calculates the period between this temporal and another temporal in terms of the specified unit.
+     * This calculates the period between two temporals in terms of a single unit. The start and end points are this and the specified temporal. The result will be negative if the end is before the start. For example, the period in hours between two temporal objects can be calculated using `startTime.until(endTime, HOURS)`.
+     *
+     * The calculation returns a whole number, representing the number of complete units between the two temporals. For example, the period in hours between the times 11:30 and 13:29 will only be one hour as it is one minute short of two hours.
+     *
+     * There are two equivalent ways of using this method. The first is to invoke this method directly. The second is to use `TemporalUnit.between(Temporal, Temporal)`:
+     *
+     * <pre>
+     *    // these two lines are equivalent
+     *    between = thisUnit.between(start, end);
+     *    between = start.until(end, thisUnit);
+     * </pre>
+     *
+     * The choice should be made based on which makes the code more readable.
+     * For example, this method allows the number of days between two dates to be calculated:
+     *
+     * <pre>
+     *    long daysBetween = DAYS.between(start, end);
+     *    // or alternatively
+     *    long daysBetween = start.until(end, DAYS);
+     * </pre>
+     *
+     * ### Specification for implementors
+     * Implementations must begin by checking to ensure that the input temporal object is of the same observable type as the implementation. They must then perform the calculation for all instances of {@link ChronoUnit}. A {@link DateTimeException} must be thrown for {@link ChronoUnit} instances that are unsupported.
+     * If the unit is not a {@link ChronoUnit}, then the result of this method is obtained by invoking `TemporalUnit.between(Temporal, Temporal)` passing this as the first argument and the input temporal as the second argument.
+     *
+     * In summary, implementations must behave in a manner equivalent to this code:
+     *
+     * <pre>
+     *   // check input temporal is the same type as this class
+     *   if (unit instanceof ChronoUnit) {
+     *     // if unit is supported, then calculate and return result
+     *     // else throw DateTimeException for unsupported units
+     *   }
+     *   return unit.between(this, endTemporal);
+     * </pre>
+     *
+     * The target object must not be altered by this method.
+     *
+     * @param {Temporal} endTemporal - the end temporal, of the same type as this object, not null
+     * @param {TemporalUnit} unit - the unit to measure the period in, not null
+     * @return {number} the amount of the period between this and the end
+     * @throws DateTimeException - if the period cannot be calculated
+     * @throws ArithmeticException - if numeric overflow occurs
+     */
+    // eslint-disable-next-line no-unused-vars
+    until(endTemporal, unit) {
+        abstractMethodFail('until');
+    }
+
+    /**
+     * function overloading for {@link Temporal.with}
+     *
+     * Called with 1 (or less) arguments, p1 is expected to be a {@link TemporalAdjuster} and {@link Temporal.withAdjuster} is called.
+     *
+     * Otherwise {@link Temporal.withFieldValue} is called.
+     *
+     * @param {!(TemporalAdjuster|TemporalField)} p1
+     * @param {number} p2
+     * @return {Temporal}
+     */
+    // eslint-disable-next-line no-unused-vars
+    with(p1, p2) {
+        if (arguments.length < 2) {
+            return this.withAdjuster(p1);
+        } else {
+            return this.withFieldValue(p1, p2);
+        }
+    }
+
+    /**
+     * Returns an adjusted object of the same type as this object with the adjustment made.
+     * This adjusts this date-time according to the rules of the specified adjuster. A simple adjuster might simply set the one of the fields, such as the year field. A more complex adjuster might set the date to the last day of the month. A selection of common adjustments is provided in {@link TemporalAdjusters}. These include finding the "last day of the month" and "next Wednesday". The adjuster is responsible for handling special cases, such as the varying lengths of month and leap years.
+     *
+     * Some example code indicating how and why this method is used:
+     *
+     * <pre>
+     *   date = date.with(Month.JULY);        // most key classes implement TemporalAdjuster
+     *   date = date.with(lastDayOfMonth());  // static import from TemporalAdjusters
+     *   date = date.with(next(WEDNESDAY));   // static import from TemporalAdjusters and DayOfWeek
+     * </pre>
+     *
+     * ### Specification for implementors
+     * Implementations must not alter either this object. Instead, an adjusted copy of the original must be returned. This provides equivalent, safe behavior for immutable and mutable implementations.
+     *
+     * @param {TemporalAdjuster} adjuster - the adjuster to use, not null
+     * @return {Temporal} an object of the same type with the specified adjustment made, not null
+     * @throws DateTimeException - if unable to make the adjustment
+     * @throws ArithmeticException - if numeric overflow occurs
+     */
+    // eslint-disable-next-line no-unused-vars
+    withAdjuster(adjuster) {
+        abstractMethodFail('withAdjuster');
+    }
+
+    /**
+     * Returns an object of the same type as this object with the specified field altered.
+     * This returns a new object based on this one with the value for the specified field changed. For example, on a {@link LocalDate}, this could be used to set the year, month or day-of-month. The returned object will have the same observable type as this object.
+     *
+     * In some cases, changing a field is not fully defined. For example, if the target object is a date representing the 31st January, then changing the month to February would be unclear. In cases like this, the field is responsible for resolving the result. Typically it will choose the previous valid date, which would be the last valid day of February in this example.
+     *
+     * ### Specification for implementors
+     * Implementations must check and handle all fields defined in {@link ChronoField}. If the field is supported, then the adjustment must be performed. If unsupported, then a {@link DateTimeException} must be thrown.
+     * If the field is not a {@link ChronoField}, then the result of this method is obtained by invoking `TemporalField.adjustInto(Temporal, long)` passing this as the first argument.
+     *
+     * Implementations must not alter either this object or the specified temporal object. Instead, an adjusted copy of the original must be returned. This provides equivalent, safe behavior for immutable and mutable implementations.
+     *
+     * @param {TemporalField} field - the field to set in the result, not null
+     * @param {number} newValue - the new value of the field in the result
+     * @return {Temporal} an object of the same type with the specified field set, not null
+     * @throws DateTimeException - if the field cannot be set
+     * @throws ArithmeticException - if numeric overflow occurs
+     */
+    // eslint-disable-next-line no-unused-vars
+    withFieldValue(field, newValue) {
+        abstractMethodFail('withFieldValue');
+    }
+}

package/src/temporal/TemporalField.js

@@ -1,3 +1,5 @@
+import { abstractMethodFail } from '../assert';
+
 /**
  * @copyright (c) 2016, Philipp Thürwächter & Pattrick Hüper
  * @copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos
@@ -21,4 +23,226 @@
  *
  * @interface
  */
-export class TemporalField {}
+export class TemporalField {
+    /**
+     * Checks if this field represents a component of a date.
+     *
+     * @return {boolean} `true` if it is a component of a date, `false` otherwise.
+     */
+    isDateBased() {
+        abstractMethodFail('isDateBased');
+    }
+
+    /**
+     * Checks if this field represents a component of a time.
+     *
+     * @return {boolean} `true` if it is a component of a time, `false` otherwise.
+     */
+    isTimeBased() {
+        abstractMethodFail('isTimeBased');
+    }
+
+    /**
+     * Gets the unit that the field is measured in.
+     *
+     * The unit of the field is the period that varies within the range.
+     * For example, in the field 'MonthOfYear', the unit is 'Months'.
+     * See also {@link rangeUnit}.
+     *
+     * @return {TemporalUnit} the period unit defining the base unit of the field.
+     */
+    baseUnit() {
+        abstractMethodFail('baseUnit');
+    }
+
+    /**
+     * Gets the range that the field is bound by.
+     * 
+     * The range of the field is the period that the field varies within.
+     * For example, in the field 'MonthOfYear', the range is 'Years'.
+     * See also {@link baseUnit}.
+     * 
+     * The range is never null. For example, the 'Year' field is shorthand for
+     * 'YearOfForever'. It therefore has a unit of 'Years' and a range of 'Forever'.
+     *
+     * @return {TemporalUnit} the period unit defining the range of the field.
+     */
+    rangeUnit() {
+        abstractMethodFail('rangeUnit');
+    }
+
+    /**
+     * Gets the range of valid values for the field.
+     *
+     * All fields can be expressed as an integer.
+     * This method returns an object that describes the valid range for that value.
+     * This method is generally only applicable to the ISO-8601 calendar system.
+     *
+     * Note that the result only describes the minimum and maximum valid values
+     * and it is important not to read too much into them. For example, there
+     * could be values within the range that are invalid for the field.
+     *
+     * @return {ValueRange} the range of valid values for the field.
+     */
+    range() {
+        abstractMethodFail('range');
+    }
+
+    /**
+     * Get the range of valid values for this field using the temporal object to
+     * refine the result.
+     *
+     * This uses the temporal object to find the range of valid values for the field.
+     * This is similar to {@link range}, however this method refines the result
+     * using the temporal. For example, if the field is {@link DAY_OF_MONTH} the
+     * {@link range} method is not accurate as there are four possible month lengths,
+     * 28, 29, 30 and 31 days. Using this method with a date allows the range to be
+     * accurate, returning just one of those four options.
+     *
+     * There are two equivalent ways of using this method.
+     * The first is to invoke this method directly.
+     * The second is to use {@link TemporalAccessor#range}:
+     * <pre>
+     *   // these two lines are equivalent, but the second approach is recommended
+     *   temporal = thisField.rangeRefinedBy(temporal);
+     *   temporal = temporal.range(thisField);
+     * </pre>
+     * It is recommended to use the second approach, {@link range},
+     * as it is a lot clearer to read in code.
+     *
+     * Implementations should perform any queries or calculations using the fields
+     * available in {@link ChronoField}.
+     * If the field is not supported a {@link DateTimeException} must be thrown.
+     *
+     * @param {!TemporalAccessor} temporal the temporal object used to refine the result.
+     * @return {ValueRange} the range of valid values for this field.
+     * @throws {DateTimeException} if the range for the field cannot be obtained.
+     * 
+     */
+    // eslint-disable-next-line no-unused-vars
+    rangeRefinedBy(temporal) {
+        abstractMethodFail('rangeRefinedBy');
+    }
+
+    /**
+     * Gets the value of this field from the specified temporal object.
+     *
+     * This queries the temporal object for the value of this field.
+     *
+     * There are two equivalent ways of using this method.
+     * The first is to invoke this method directly.
+     * The second is to use {@link TemporalAccessor#get}:
+     * <pre>
+     *   // these two lines are equivalent, but the second approach is recommended
+     *   temporal = thisField.getFrom(temporal);
+     *   temporal = temporal.get(thisField);
+     * </pre>
+     * It is recommended to use the second approach, as it is a lot clearer to read in code.
+     *
+     * Implementations should perform any queries or calculations using the fields
+     * available in {@link ChronoField}.
+     * If the field is not supported a {@link DateTimeException} must be thrown.
+     *
+     * @param {!TemporalAccesor} temporal the temporal object to query.
+     * @return {number} the value of this field.
+     * @throws {DateTimeException} if a value for the field cannot be obtained.
+     */
+    // eslint-disable-next-line no-unused-vars
+    getFrom(temporal) {
+        abstractMethodFail('getFrom');
+    }
+
+    /**
+     * Returns a copy of the specified temporal object with the value of this field set.
+     *
+     * This returns a new temporal object based on the specified one with the value for
+     * this field changed. For example, on a {@link LocalDate}, this could be used to
+     * set the year, month or day-of-month.
+     * The returned object has the same observable type as the specified object.
+     *
+     * In some cases, changing a field is not fully defined. For example, if the target object is
+     * a date representing the 31st January, then changing the month to February would be unclear.
+     * In cases like this, the implementation is responsible for resolving the result.
+     * Typically it will choose the previous valid date, which would be the last valid
+     * day of February in this example.
+     *
+     * There are two equivalent ways of using this method.
+     * The first is to invoke this method directly.
+     * The second is to use {@link Temporal#with}:
+     * <pre>
+     *   // these two lines are equivalent, but the second approach is recommended
+     *   temporal = thisField.adjustInto(temporal);
+     *   temporal = temporal.with(thisField);
+     * </pre>
+     * It is recommended to use the second approach, `with(temporal)`,
+     * as it is a lot clearer to read in code.
+     *
+     * Implementations should perform any queries or calculations using the fields
+     * available in {@link ChronoField}.
+     * If the field is not supported a {@link DateTimeException} must be thrown.
+     *
+     * Implementations must not alter the specified temporal object.
+     * Instead, an adjusted copy of the original must be returned.
+     * This provides equivalent, safe behavior for immutable and mutable implementations.
+     *
+     * @param {!Temporal} temporal the temporal object to adjust.
+     * @param {!number} newValue the new value of the field.
+     * @return {Temporal} the adjusted temporal object.
+     * @throws {DateTimeException} if the field cannot be set.
+     */
+    // eslint-disable-next-line no-unused-vars
+    adjustInto(temporal, newValue) {
+        abstractMethodFail('adjustInto');
+    }
+
+    /**
+     * Checks if this field is supported by the temporal object.
+     *
+     * This determines whether the temporal accessor supports this field.
+     * If this returns false, the the temporal cannot be queried for this field.
+     *
+     * There are two equivalent ways of using this method.
+     * The first is to invoke this method directly.
+     * The second is to use {@link TemporalAccessor#isSupported}:
+     * <pre>
+     *   // these two lines are equivalent, but the second approach is recommended
+     *   temporal = thisField.isSupportedBy(temporal);
+     *   temporal = temporal.isSupported(thisField);
+     * </pre>
+     * It is recommended to use the second approach, `isSupported(temporal)`,
+     * as it is a lot clearer to read in code.
+     *
+     * Implementations should determine whether they are supported using the fields
+     * available in {@link ChronoField}.
+     *
+     * @param {!TemporalAccesor} temporal the temporal object to query.
+     * @return {boolean} `true` if the date-time can be queried for this field, `false` if not.
+     */
+    // eslint-disable-next-line no-unused-vars
+    isSupportedBy(temporal) {
+        abstractMethodFail('isSupportedBy');
+    }
+
+    /**
+     * @return {string}
+     */
+    displayName(/* TODO: locale */) {
+        abstractMethodFail('displayName');
+    }
+
+    /**
+    * @param {*} other
+    * @returns {boolean}
+    */
+    // eslint-disable-next-line no-unused-vars
+    equals(other) {
+        abstractMethodFail('equals');
+    }
+
+    /**
+     * @returns {string}
+     */
+    name() {
+        abstractMethodFail('name');
+    }
+}

package/src/temporal/TemporalUnit.js

@@ -32,14 +32,14 @@ export class TemporalUnit {
      *
      * All units return a duration measured in standard nanoseconds from this method.
      * The duration will be positive and non-zero.
-     * For example, an hour has a duration of `60 * 60 * 1,000,000,000ns`.
+     * For example, an hour has a duration of `60 * 60 * 1,000,000,000 ns`.
      *
      * Some units may return an accurate duration while others return an estimate.
      * For example, days have an estimated duration due to the possibility of
      * daylight saving time changes.
      * To determine if the duration is an estimate, use {@link isDurationEstimated}.
      *
-     * @return {Duration} the duration of this unit, which may be an estimate, not null
+     * @return {Duration} the duration of this unit, which may be an estimate.
      */
     duration() {
         abstractMethodFail('duration');
@@ -54,7 +54,7 @@ export class TemporalUnit {
      * This method returns true if the duration is an estimate and false if it is
      * accurate. Note that accurate/estimated ignores leap seconds.
      *
-     * @return {boolean} true if the duration is estimated, false if accurate
+     * @return {boolean} `true` if the duration is estimated, `false` if accurate.
      */
     isDurationEstimated() {
         abstractMethodFail('isDurationEstimated');
@@ -63,7 +63,7 @@ export class TemporalUnit {
     /**
      * Checks if this unit is date-based.
      *
-     * @return {boolean} true if date-based
+     * @return {boolean} `true` if date unit, `false` if a time unit.
      */
     isDateBased() {
         abstractMethodFail('isDateBased');
@@ -72,7 +72,7 @@ export class TemporalUnit {
     /**
      * Checks if this unit is time-based.
      *
-     * @return {boolean} true if time-based
+     * @return {boolean} `true` if time unit, `false` if a date unit.
      */
     isTimeBased() {
         abstractMethodFail('isTimeBased');
@@ -85,8 +85,8 @@ export class TemporalUnit {
      * This checks that the implementing date-time can add/subtract this unit.
      * This can be used to avoid throwing an exception.
      *
-     * @param {Temporal} temporal  the temporal object to check, not null
-     * @return {boolean} true if the unit is supported
+     * @param {!Temporal} temporal the temporal object to check.
+     * @return {boolean} `true` if the unit is supported.
      */
     // eslint-disable-next-line no-unused-vars
     isSupportedBy(temporal) {
@@ -120,10 +120,10 @@ export class TemporalUnit {
      * Instead, an adjusted copy of the original must be returned.
      * This provides equivalent, safe behavior for immutable and mutable implementations.
      *
-     * @param {Temporal} dateTime  the temporal object to adjust, not null
-     * @param {number} periodToAdd  the period of this unit to add, positive or negative
-     * @return {Temporal} the adjusted temporal object, not null
-     * @throws DateTimeException if the period cannot be added
+     * @param {!Temporal} dateTime the temporal object to adjust.
+     * @param {number} periodToAdd the period of this unit to add, positive or negative.
+     * @return {Temporal} the adjusted temporal object.
+     * @throws DateTimeException if the period cannot be added.
      */
     // eslint-disable-next-line no-unused-vars
     addTo(dateTime, periodToAdd) {
@@ -141,7 +141,7 @@ export class TemporalUnit {
      * using {@link HOURS.between}.
      *
      * The calculation returns a whole number, representing the number of complete units between the two temporals.
-     * For example, the period in hours between the times 11:30 and 13:29 will only b
+     * For example, the period in hours between the times 11:30 and 13:29 will only be
      * one hour as it is one minute short of two hours.
      *
      * There are two equivalent ways of using this method.
@@ -162,19 +162,18 @@ export class TemporalUnit {
      * </pre>
      * Implementations should perform any queries or calculations using the units available in
      * {@link ChronoUnit} or the fields available in {@link ChronoField}.
-     * If the unit is not supported a DateTimeException must be thrown.
+     * If the unit is not supported a {@link DateTimeException} must be thrown.
      * Implementations must not alter the specified temporal objects.
      *
-     * @param {Temporal} temporal1  the base temporal object, not null
-     * @param {Temporal} temporal2  the other temporal object, not null
+     * @param {!Temporal} temporal1 the base temporal object.
+     * @param {!Temporal} temporal2 the other temporal object.
      * @return {number} the period between temporal1 and temporal2 in terms of this unit;
-     *  positive if temporal2 is later than temporal1, negative if earlier
-     * @throws DateTimeException if the period cannot be calculated
-     * @throws ArithmeticException if numeric overflow occurs
+     *  positive if temporal2 is later than temporal1, negative if earlier.
+     * @throws DateTimeException if the period cannot be calculated.
+     * @throws ArithmeticException if numeric overflow occurs.
      */
     // eslint-disable-next-line no-unused-vars
     between(temporal1, temporal2) {
         abstractMethodFail('between');
     }
-
 }

package/src/temporal/ValueRange.js

@@ -115,6 +115,7 @@ export class ValueRange {
             }
             return assert(false, msg, DateTimeException);
         }
+        return value;
     }
 
     /**