@js-joda/core - npm Package Compare versions

Comparing version 2.0.0 to 3.0.0

CHANGELOG.md

 Changelog
 =========
 
-### next
+### next (upcoming)
 
+
+### 3.0.0
+
+This is a major release because of these following minor/ breaking cleanups:
+
+* Renamed method getDisplayName to displayName for
+   * WeekFields 
+   * DayOfWeek
+   * Month
+   * IsoFields
+* Removed duplicate function YearMonth.with(number, number)
+   * YearMonth.with(year, month), use YearMonth.of() instead
+   * YearMonth.withYearMonth(year, month), use YearMonth.of() instead
+
+All updates:
+
+ * Implement OffsetTime and OffsetDateTim #416 by exoego
+ * TS types reorganized and documentation added #418 by InExtremaRes
+ * Fix isBrowserTest check #419 by pithu
+ * Duration#(minus|plus) should accept TemporalUnit, not just ChronoUnit #417 by exoego
+ * TS types refactor part 1 #415 by InExtremaRes
+ * Remove YearMonth#with that takes (number, number) #412 by InExtremaRes
+ * Fixes and cleanups to TemporalFields and TemporalUnits #408 by InExtremaRes
+ * Switch to travis-ci.com #409 by pithu
+ * Error base name changed to "JsJodaException" and exceptions exposed in TS #407 by InExtremaRes
+ * Some fixes to TS declarations #404 by InExtremaRes
+ * remove android saucelabs test setup #403 by pithu
+ * Fix TS declarations of some TemporalAdjuster implementations (like DayOfWeak) #402 by InExtremaRes
+ * Fixed types of DateTimeFormatterBuilder.prototype.toFormatter to allow zero arguments  #388 by InExtremaRes
+ * Add missing types for Clock.offset() #387 by InExtremaRes  
+ * Added missing nanoAdjustment to Duration.ofSeconds static method #383 by jseter
+ * changed bitwise or to logical or #379 by bowersj 
+ * Add Typescript for IsoChronology.INSTANCE #373 by cranberyxl 
+ * Remove `withTemporalAdjuster` and others non-public methods from TS declaration #363 by InExtremaRes
+
 ### 2.0.0
@@ -7,0 +42,0 @@

package.json

 {
   "name": "@js-joda/core",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "description": "a date and time library for javascript",
@@ -22,8 +22,8 @@ "repository": {
     "prepublish": "npm run build-dist",
-    "test": "NODE_ENV=test ./node_modules/.bin/mocha --timeout 5000 --require @babel/register ./test/*Test.js ./test/**/*Test.js ./test/**/**/*Test.js ./test/*Test_mochaOnly.js",
+    "test": "NODE_ENV=test ./node_modules/.bin/mocha --timeout 5000 --require @babel/register ./test/*Test_mochaOnly.js ./test/*Test.js ./test/**/*Test.js ./test/**/**/*Test.js",
     "test-coverage": "NODE_ENV=test COVERAGE=1 ../../node_modules/.bin/nyc --report-dir=build/coverage --reporter=lcov --reporter html ./node_modules/.bin/mocha --timeout 5000 --require @babel/register --reporter progress ./test/*Test.js ./test/**/*Test.js ./test/**/**/*Test.js",
     "test-browser": "./node_modules/.bin/karma start --reporters=dots --single-run",
-    "test-saucelabs": "./node_modules/.bin/karma start --reporters=\"dots,saucelabs\" --browsers=\"sl_chrome,sl_ie,sl_firefox,sl_android_simulator,sl_ios_simulator\" --single-run=true",
+    "test-saucelabs": "./node_modules/.bin/karma start --reporters=\"dots,saucelabs\" --browsers=\"sl_chrome,sl_ie,sl_firefox,sl_ios_simulator\" --single-run=true",
     "test-ci": "npm run build-dist && npm run test && npm run test-browser -- --browsers \"Firefox,PhantomJS\" && npm run test-ts-definitions && npm run test-coverage",
-    "test-ts-definitions": "tsc --noImplicitAny --strict --noEmit --pretty --lib ES6 test/typescript_definitions/js-joda-tests.ts",
+    "test-ts-definitions": "tsc -p test/typescript_definitions/tsconfig.json",
     "build-dist": "npx rollup -c rollup.config.js",
@@ -30,0 +30,0 @@ "build-md-toc": "./node_modules/.bin/markdown-toc -i CheatSheet.md",

src/_init.js

@@ -15,2 +15,4 @@ /*
 import {_init as MonthDayInit} from './MonthDay';
+import {_init as OffsetDateTimeInit} from './OffsetDateTime';
+import {_init as OffsetTimeInit} from './OffsetTime';
 import {_init as PeriodInit} from './Period';
@@ -63,4 +65,6 @@ import {_init as YearInit} from './Year';
     DateTimeFormatterBuilderInit();
+    OffsetDateTimeInit();
+    OffsetTimeInit();
 }
 
 init();

src/DayOfWeek.js

@@ -158,3 +158,3 @@ /*
     // eslint-disable-next-line no-unused-vars
-    getDisplayName(style, locale) {
+    displayName(style, locale) {
         throw new IllegalArgumentException('Pattern using (localized) text not implemented yet!');
@@ -161,0 +161,0 @@ // return new DateTimeFormatterBuilder().appendText(ChronoField.DAY_OF_WEEK, style).toFormatter(locale).format(this);

src/Duration.js

@@ -723,3 +723,3 @@ /**
      * @param {!(Duration|number)} durationOrNumber
-     * @param {?ChronoUnit} unit
+     * @param {?TemporalUnit} unit
      * @return {Duration}
@@ -726,0 +726,0 @@ */

src/errors.js

@@ -7,4 +7,4 @@ /**
 function createErrorType(name, init, superErrorClass = Error) {
-    function E(message) {
-        if (!Error.captureStackTrace){
+    function JsJodaException(message) {
+        if (!Error.captureStackTrace) {
             this.stack = (new Error()).stack;
@@ -20,6 +20,6 @@ } else {
     }
-    E.prototype = new superErrorClass();
-    E.prototype.name = name;
-    E.prototype.constructor = E;
-    return E;
+    JsJodaException.prototype = Object.create(superErrorClass.prototype);
+    JsJodaException.prototype.name = name;
+    JsJodaException.prototype.constructor = JsJodaException;
+    return JsJodaException;
 }
@@ -26,0 +26,0 @@

src/Instant.js

@@ -14,2 +14,3 @@ /**
 import {MathUtil} from './MathUtil';
+import {OffsetDateTime} from './OffsetDateTime';
 
@@ -867,5 +868,5 @@ import {Temporal} from './temporal/Temporal';
      */
-    //atOffset(offset) {
-    //    return OffsetDateTime.ofInstant(this, offset);
-    //}
+    atOffset(offset) {
+        return OffsetDateTime.ofInstant(this, offset);
+    }
 
@@ -872,0 +873,0 @@ /**

src/js-joda.js

@@ -25,2 +25,4 @@ /**
 import { MonthDay } from './MonthDay';
+import { OffsetDateTime } from './OffsetDateTime';
+import { OffsetTime } from './OffsetTime';
 import { Period } from './Period';
@@ -109,2 +111,4 @@ import { Year } from './Year';
     LocalDateTime,
+    OffsetTime,
+    OffsetDateTime,
     Month,
@@ -172,2 +176,4 @@ MonthDay,
     MonthDay,
+    OffsetTime,
+    OffsetDateTime,
     Period,
@@ -174,0 +180,0 @@ Year,

src/Month.js

@@ -90,3 +90,3 @@ /**
     // eslint-disable-next-line no-unused-vars
-    getDisplayName(style, locale) {
+    displayName(style, locale) {
         // TODO:
@@ -93,0 +93,0 @@ throw new IllegalArgumentException('Pattern using (localized) text not implemented yet!');

src/Period.js

@@ -79,3 +79,3 @@ /*
 
-        if((_years | _months | _days) === 0){
+        if( _years === 0 && _months === 0 && _days === 0 ){
             if (!Period.ZERO) {
@@ -82,0 +82,0 @@ this._years = _years;

src/temporal/ChronoField.js

@@ -25,64 +25,185 @@ /**
  *
- * ### Static properties of Class {@link ChronoField}
+ * ### Static properties:
  *
- * ChronoField.NANO_OF_SECOND
- *
- * ChronoField.NANO_OF_DAY
- *
- * ChronoField.MICRO_OF_SECOND
- *
- * ChronoField.MICRO_OF_DAY
- *
- * ChronoField.MILLI_OF_SECOND
- *
- * ChronoField.MILLI_OF_DAY
- *
- * ChronoField.SECOND_OF_MINUTE
- *
- * ChronoField.SECOND_OF_DAY
- *
- * ChronoField.MINUTE_OF_HOUR
- *
- * ChronoField.MINUTE_OF_DAY
- *
- * ChronoField.HOUR_OF_AMPM
- *
- * ChronoField.CLOCK_HOUR_OF_AMPM
- *
- * ChronoField.HOUR_OF_DAY
- *
- * ChronoField.CLOCK_HOUR_OF_DAY
- *
- * ChronoField.AMPM_OF_DAY
- *
- * ChronoField.DAY_OF_WEEK
- *
- * ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH
- *
- * ChronoField.ALIGNED_DAY_OF_WEEK_IN_YEAR
- *
- * ChronoField.DAY_OF_MONTH
- *
- * ChronoField.DAY_OF_YEAR
- *
- * ChronoField.EPOCH_DAY
- *
- * ChronoField.ALIGNED_WEEK_OF_MONTH
- *
- * ChronoField.ALIGNED_WEEK_OF_YEAR
- *
- * ChronoField.MONTH_OF_YEAR
- *
- * ChronoField.PROLEPTIC_MONTH
- *
- * ChronoField.YEAR_OF_ERA
- *
- * ChronoField.YEAR
- *
- * ChronoField.ERA
- *
- * ChronoField.INSTANT_SECONDS
- *
- * ChronoField.OFFSET_SECONDS
- *
+ * - `ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH`: This represents concept of the count of
+ * days within the period of a week where the weeks are aligned to the start of the month.
+ * This field is typically used with `ALIGNED_WEEK_OF_MONTH`.
+ * 
+ * - `ChronoField.ALIGNED_DAY_OF_WEEK_IN_YEAR`: This represents concept of the count of days
+ * within the period of a week where the weeks are aligned to the start of the year.
+ * This field is typically used with `ALIGNED_WEEK_OF_YEAR`.
+ * 
+ * - `ChronoField.ALIGNED_WEEK_OF_MONTH`: This represents concept of the count of weeks within
+ * the period of a month where the weeks are aligned to the start of the month. This field
+ * is typically used with `ALIGNED_DAY_OF_WEEK_IN_MONTH`.
+ * 
+ * - `ChronoField.ALIGNED_WEEK_OF_YEAR`: This represents concept of the count of weeks within
+ * the period of a year where the weeks are aligned to the start of the year. This field
+ * is typically used with `ALIGNED_DAY_OF_WEEK_IN_YEAR`.
+ * 
+ * - `ChronoField.AMPM_OF_DAY`: This counts the AM/PM within the day, from 0 (AM) to 1 (PM).
+ * 
+ * - `ChronoField.CLOCK_HOUR_OF_AMPM`: This counts the hour within the AM/PM, from 1 to 12.
+ * This is the hour that would be observed on a standard 12-hour analog wall clock.
+ * 
+ * - `ChronoField.CLOCK_HOUR_OF_DAY`: This counts the hour within the AM/PM, from 1 to 24.
+ * This is the hour that would be observed on a 24-hour analog wall clock.
+ * 
+ * - `ChronoField.DAY_OF_MONTH`: This represents the concept of the day within the month.
+ * In the default ISO calendar system, this has values from 1 to 31 in most months.
+ * April, June, September, November have days from 1 to 30, while February has days from
+ * 1 to 28, or 29 in a leap year.
+ * 
+ * - `ChronoField.DAY_OF_WEEK`: This represents the standard concept of the day of the week.
+ * In the default ISO calendar system, this has values from Monday (1) to Sunday (7).
+ * The {@link DayOfWeek} class can be used to interpret the result.
+ * 
+ * - `ChronoField.DAY_OF_YEAR`: This represents the concept of the day within the year.
+ * In the default ISO calendar system, this has values from 1 to 365 in standard years and
+ * 1 to 366 in leap years.
+ * 
+ * - `ChronoField.EPOCH_DAY`: This field is the sequential count of days where
+ * 1970-01-01 (ISO) is zero. Note that this uses the local time-line, ignoring offset and
+ * time-zone.
+ * 
+ * - `ChronoField.ERA`: This represents the concept of the era, which is the largest
+ * division of the time-line. This field is typically used with `YEAR_OF_ERA`.
+ * 
+ *     In the default ISO calendar system, there are two eras defined, 'BCE' and 'CE'. The era
+ * 'CE' is the one currently in use and year-of-era runs from 1 to the maximum value.
+ * The era 'BCE' is the previous era, and the year-of-era runs backwards.
+ * 
+ * - `ChronoField.HOUR_OF_AMPM`: This counts the hour within the AM/PM, from 0 to 11.
+ * This is the hour that would be observed on a standard 12-hour digital clock.
+ * 
+ * - `ChronoField.HOUR_OF_DAY`: This counts the hour within the day, from 0 to 23. This is
+ * the hour that would be observed on a standard 24-hour digital clock.
+ * 
+ * - `ChronoField.INSTANT_SECONDS`: This represents the concept of the sequential count of
+ * seconds where 1970-01-01T00:00Z (ISO) is zero. This field may be used with `NANO_OF_DAY`
+ * to represent the fraction of the day.
+ * 
+ *     An Instant represents an instantaneous point on the time-line. On their own they have
+ * no elements which allow a local date-time to be obtained. Only when paired with an offset
+ * or time-zone can the local date or time be found. This field allows the seconds part of
+ * the instant to be queried.
+ * 
+ * - `ChronoField.MICRO_OF_DAY`: This counts the microsecond within the day, from 0 to
+ * (24 * 60 * 60 * 1,000,000) - 1.
+ * 
+ *     This field is used to represent the micro-of-day handling any fraction of the second.
+ * Implementations of {@link TemporalAccessor} should provide a value for this field if they
+ * can return a value for `SECOND_OF_DAY` filling unknown precision with zero.
+ * 
+ *     When this field is used for setting a value, it should behave in the same way as
+ * setting `NANO_OF_DAY` with the value multiplied by 1,000.
+ * 
+ * - `ChronoField.MICRO_OF_SECOND`: This counts the microsecond within the second, from 0
+ * to 999,999.
+ * 
+ *     This field is used to represent the micro-of-second handling any fraction of the second.
+ * Implementations of {@link TemporalAccessor} should provide a value for this field if they
+ * can return a value for `SECOND_OF_MINUTE`, `SECOND_OF_DAY` or `INSTANT_SECONDS` filling
+ * unknown precision with zero.
+ * 
+ * - `ChronoField.MILLI_OF_DAY`: This counts the millisecond within the day, from 0 to
+ * (24 * 60 * 60 * 1,000) - 1.
+ * 
+ *     This field is used to represent the milli-of-day handling any fraction of the second.
+ * Implementations of {@link TemporalAccessor} should provide a value for this field if they
+ * can return a value for `SECOND_OF_DAY` filling unknown precision with zero.
+ * 
+ *     When this field is used for setting a value, it should behave in the same way as
+ * setting `NANO_OF_DAY` with the value multiplied by 1,000,000.
+ * 
+ * - `ChronoField.MILLI_OF_SECOND`: This counts the millisecond within the second, from 0 to
+ * 999.
+ * 
+ *     This field is used to represent the milli-of-second handling any fraction of the second.
+ * Implementations of {@link TemporalAccessor} should provide a value for this field if they can
+ * return a value for `SECOND_OF_MINUTE`, `SECOND_OF_DAY` or `INSTANT_SECONDS` filling unknown
+ * precision with zero.
+ * 
+ *     When this field is used for setting a value, it should behave in the same way as
+ * setting `NANO_OF_SECOND` with the value multiplied by 1,000,000.
+ * 
+ * - `ChronoField.MINUTE_OF_DAY`: This counts the minute within the day, from 0 to (24 * 60) - 1.
+ * 
+ * - `ChronoField.MINUTE_OF_HOUR`: This counts the minute within the hour, from 0 to 59.
+ * 
+ * - `ChronoField.MONTH_OF_YEAR`: The month-of-year, such as March. This represents the concept
+ * of the month within the year. In the default ISO calendar system, this has values from
+ * January (1) to December (12).
+ * 
+ * - `ChronoField.NANO_OF_DAY`: This counts the nanosecond within the day, from 0 to
+ * (24 * 60 * 60 * 1,000,000,000) - 1.
+ * 
+ *     This field is used to represent the nano-of-day handling any fraction of the second.
+ * Implementations of {@link TemporalAccessor} should provide a value for this field if they
+ * can return a value for `SECOND_OF_DAY` filling unknown precision with zero.
+ * 
+ * - `ChronoField.NANO_OF_SECOND`: This counts the nanosecond within the second, from 0
+ * to 999,999,999.
+ * 
+ *     This field is used to represent the nano-of-second handling any fraction of the second.
+ * Implementations of {@link TemporalAccessor} should provide a value for this field if they
+ * can return a value for `SECOND_OF_MINUTE`, `SECOND_OF_DAY` or `INSTANT_SECONDS` filling
+ * unknown precision with zero.
+ * 
+ *     When this field is used for setting a value, it should set as much precision as the
+ * object stores, using integer division to remove excess precision. For example, if the
+ * {@link TemporalAccessor} stores time to millisecond precision, then the nano-of-second must
+ * be divided by 1,000,000 before replacing the milli-of-second.
+ * 
+ * - `ChronoField.OFFSET_SECONDS`: This represents the concept of the offset in seconds of
+ * local time from UTC/Greenwich.
+ * 
+ *     A {@link ZoneOffset} represents the period of time that local time differs from
+ * UTC/Greenwich. This is usually a fixed number of hours and minutes. It is equivalent to
+ * the total amount of the offset in seconds. For example, during the winter Paris has an
+ * offset of +01:00, which is 3600 seconds.
+ * 
+ * - `ChronoField.PROLEPTIC_MONTH`: The proleptic-month, which counts months sequentially
+ * from year 0.
+ * 
+ *     The first month in year zero has the value zero. The value increase for later months
+ * and decrease for earlier ones. Note that this uses the local time-line, ignoring offset
+ * and time-zone.
+ * 
+ * - `ChronoField.SECOND_OF_DAY`: This counts the second within the day, from 0 to
+ * (24 * 60 * 60) - 1.
+ * 
+ * - `ChronoField.SECOND_OF_MINUTE`: This counts the second within the minute, from 0 to 59.
+ * 
+ * - `ChronoField.YEAR`: The proleptic year, such as 2012. This represents the concept of
+ * the year, counting sequentially and using negative numbers. The proleptic year is not
+ * interpreted in terms of the era.
+ * 
+ *     The standard mental model for a date is based on three concepts - year, month and day.
+ * These map onto the `YEAR`, `MONTH_OF_YEAR` and `DAY_OF_MONTH` fields. Note that there is no
+ * reference to eras. The full model for a date requires four concepts - era, year, month and
+ * day. These map onto the `ERA`, `YEAR_OF_ERA`, `MONTH_OF_YEAR` and `DAY_OF_MONTH` fields.
+ * Whether this field or `YEAR_OF_ERA` is used depends on which mental model is being used.
+ * 
+ * - `ChronoField.YEAR_OF_ERA`: This represents the concept of the year within the era. This
+ * field is typically used with `ERA`. The standard mental model for a date is based on three
+ * concepts - year, month and day. These map onto the `YEAR`, `MONTH_OF_YEAR` and
+ * `DAY_OF_MONTH` fields. Note that there is no reference to eras. The full model for a date
+ * requires four concepts - era, year, month and day. These map onto the `ERA`, `YEAR_OF_ERA`,
+ * `MONTH_OF_YEAR` and `DAY_OF_MONTH` fields. Whether this field or `YEAR` is used depends on
+ * which mental model is being used.
+ * 
+ *     In the default ISO calendar system, there are two eras defined, 'BCE' and 'CE'.
+ * The era 'CE' is the one currently in use and year-of-era runs from 1 to the maximum value.
+ * The era 'BCE' is the previous era, and the year-of-era runs backwards.
+ * 
+ *     For example, subtracting a year each time yield the following:
+ *    - year-proleptic 2 = 'CE' year-of-era 2
+ *    - year-proleptic 1 = 'CE' year-of-era 1
+ *    - year-proleptic 0 = 'BCE' year-of-era 1
+ *    - year-proleptic -1 = 'BCE' year-of-era 2
+ * 
+ *     Note that the ISO-8601 standard does not actually define eras. Note also that the
+ * ISO eras do not align with the well-known AD/BC eras due to the change between the Julian
+ * and Gregorian calendar systems.
  */
@@ -96,2 +217,3 @@ export class ChronoField extends TemporalField {
      * @return {ChronoField | null}
+     * @private
      */
@@ -111,4 +233,4 @@ static byName(fieldName) {
      * @param {!string} name
-     * @param {!number} baseUnit
-     * @param {!number} rangeUnit
+     * @param {!TemporalUnit} baseUnit
+     * @param {!TemporalUnit} rangeUnit
      * @param {!ValueRange} range
@@ -126,4 +248,3 @@ * @private
     /**
-     *
-     * @returns {string}
+     * @return {string}
      */
@@ -135,4 +256,3 @@ name(){
     /**
-     *
-     * @returns {!number}
+     * @return {TemporalUnit} the period unit defining the base unit of the field.
      */
@@ -144,4 +264,3 @@ baseUnit(){
     /**
-     *
-     * @returns {!number}
+     * @return {TemporalUnit} the period unit defining the range of the field.
      */
@@ -153,4 +272,3 @@ rangeUnit(){
     /**
-     *
-     * @returns {!ValueRange}
+     * @return {ValueRange} the range of valid values for the field.
      */
@@ -162,3 +280,2 @@ range(){
     /**
-     *
      * @returns {string}
@@ -171,15 +288,35 @@ */
     /**
+     * Checks that the specified value is valid for this field.
      *
-     * @param {number} value
-     * @returns {*}
+     * This validates that the value is within the outer range of valid values
+     * returned by {@link range}.
+     *
+     * This method checks against the range of the field in the ISO-8601 calendar system.
+     *
+     * @param {!number} value the value to check.
+     * @returns {number} the value that was passed in.
      */
     checkValidValue(value) {
-        return this.range().checkValidValue(value, this.name());
+        return this.range().checkValidValue(value, this);
     }
 
     /**
-     * Checks if this field represents a component of a date.
+     * Checks that the specified value is valid and fits in an `int`.
      *
-     * @return {boolean} true if it is a component of a date
+     * This validates that the value is within the outer range of valid values
+     * returned by {@link range}.
+     * It also checks that all valid values are within the bounds of an `int`.
+     *
+     * This method checks against the range of the field in the ISO-8601 calendar system.
+     *
+     * @param {number} value the value to check.
+     * @return {number} the value that was passed in.
      */
+    checkValidIntValue(value) {
+        return this.range().checkValidIntValue(value, this);
+    }
+
+    /**
+     * @return {boolean} `true` if it is a component of a date, `false` otherwise.
+     */
     isDateBased() {
@@ -204,5 +341,3 @@ const dateBased =
     /**
-     * Checks if this field represents a component of a time.
-     *
-     * @return {boolean} true if it is a component of a time
+     * @return {boolean} `true` if it is a component of a time, `false` otherwise.
      */
@@ -230,30 +365,5 @@ isTimeBased() {
     /**
-     * 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, not null
-     * @return {ValueRange} the range of valid values for this field, not null
-     * @throws DateTimeException if the range for the field cannot be obtained
+     * @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.
      */
@@ -264,25 +374,8 @@ rangeRefinedBy(temporal) {
 
-    /**
-     * Checks that the specified value is valid and fits in an `int`.
-     *
-     * This validates that the value is within the outer range of valid values
-     * returned by {@link range}.
-     * It also checks that all valid values are within the bounds of an `int`.
-     *
-     * This method checks against the range of the field in the ISO-8601 calendar system.
-     * This range may be incorrect for other calendar systems.
-     * Use {@link Chronology#range} to access the correct range
-     * for a different calendar system.
-     *
-     * @param {number} value - the value to check
-     * @return {number} the value that was passed in
-     */
-    checkValidIntValue(value) {
-        return this.range().checkValidIntValue(value, this);
-    }
+    
 
     /**
-     *
-     * @param {TemporalAccessor} temporal
-     * @returns {number}
+     * @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.
      */
@@ -294,3 +387,2 @@ getFrom(temporal) {
     /**
-     *
      * @returns {string}
@@ -303,3 +395,2 @@ */
     /**
-     *
      * @param {*} other
@@ -311,2 +402,20 @@ * @returns {boolean}
     }
+
+    /**
+     * @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.
+     */
+    adjustInto(temporal, newValue) {
+        return temporal.with(this, newValue);
+    }
+
+    /**
+     * @param {!TemporalAccesor} temporal the temporal object to query.
+     * @return {boolean} `true` if the date-time can be queried for this field, `false` if not.
+     */
+    isSupportedBy(temporal) {
+        return temporal.isSupported(this);
+    }
 }
@@ -377,2 +486,1 @@
 }
-

src/temporal/ChronoUnit.js

@@ -24,116 +24,55 @@ /**
  *
- * ### Static properties of Class {@link ChronoUnit}
+ * ### Static properties:
+ * 
+ * - `ChronoUnit.CENTURIES`: Unit that represents the concept of a century. For the ISO calendar
+ * system, it is equal to 100 years.
+ * 
+ * - `ChronoUnit.DAYS`: Unit that represents the concept of a day. For the ISO calendar system, it
+ * is the standard day from midnight to midnight. The estimated duration of a day is 24 Hours.
+ * 
+ * - `ChronoUnit.DECADES`: Unit that represents the concept of a decade. For the ISO calendar system,
+ * it is equal to 10 years.
+ * 
+ * - `ChronoUnit.ERAS`: Unit that represents the concept of an era. The ISO calendar system doesn't
+ * have eras thus it is impossible to add an era to a date or date-time. The estimated duration of the
+ * era is artificially defined as 1,000,000,000 Years.
+ * 
+ * - `ChronoUnit.FOREVER`: Artificial unit that represents the concept of forever. This is primarily
+ * used with {@link TemporalField} to represent unbounded fields such as the year or era. The
+ * estimated duration of the era is artificially defined as the largest duration supported by
+ * {@link Duration}.
+ * 
+ * - `ChronoUnit.HALF_DAYS`: Unit that represents the concept of half a day, as used in AM/PM. For
+ * the ISO calendar system, it is equal to 12 hours.
  *
- * ChronoUnit.NANOS
- *
- * Unit that represents the concept of a nanosecond, the smallest supported unit of time.
- * For the ISO calendar system, it is equal to the 1,000,000,000th part of the second unit.
- *
- * ChronoUnit.MICROS
- *
- * Unit that represents the concept of a microsecond.
- * For the ISO calendar system, it is equal to the 1,000,000th part of the second unit.
- *
- * ChronoUnit.MILLIS
- *
- * Unit that represents the concept of a millisecond.
- * For the ISO calendar system, it is equal to the 1000th part of the second unit.
- *
- * ChronoUnit.SECONDS
- *
- * Unit that represents the concept of a second.
- * For the ISO calendar system, it is equal to the second in the SI system
- * of units, except around a leap-second.
- *
- * ChronoUnit.MINUTES
- *
- * Unit that represents the concept of a minute.
- * For the ISO calendar system, it is equal to 60 seconds.
- *
- * ChronoUnit.HOURS
- *
- * Unit that represents the concept of an hour.
- * For the ISO calendar system, it is equal to 60 minutes.
- *
- * ChronoUnit.HALF_DAYS
- *
- * Unit that represents the concept of half a day, as used in AM/PM.
- * For the ISO calendar system, it is equal to 12 hours.
- *
- * ChronoUnit.DAYS
- *
- * Unit that represents the concept of a day.
- * For the ISO calendar system, it is the standard day from midnight to midnight.
- * The estimated duration of a day is 24 hours.
- *
- * When used with other calendar systems it must correspond to the day defined by
- * the rising and setting of the Sun on Earth. It is not required that days begin
- * at midnight - when converting between calendar systems, the date should be
- * equivalent at midday.
- *
- * ChronoUnit.WEEKS
- *
- * Unit that represents the concept of a week.
- * For the ISO calendar system, it is equal to 7 days.
- *
- * When used with other calendar systems it must correspond to an integral number of days.
- *
- * ChronoUnit.MONTHS
- *
- * Unit that represents the concept of a month.
- * For the ISO calendar system, the length of the month varies by month-of-year.
- * The estimated duration of a month is one twelfth of 365.2425 days.
- *
- * When used with other calendar systems it must correspond to an integral number of days.
- *
- * ChronoUnit.YEARS
- *
- * Unit that represents the concept of a year.
- * For the ISO calendar system, it is equal to 12 months.
- * The estimated duration of a year is 365.2425 days.
- *
- * When used with other calendar systems it must correspond to an integral number of days
- * or months roughly equal to a year defined by the passage of the Earth around the Sun.
- *
- * ChronoUnit.DECADES
- *
- * Unit that represents the concept of a decade.
- * For the ISO calendar system, it is equal to 10 years.
- *
- * When used with other calendar systems it must correspond to an integral number of days
- * and is normally an integral number of years.
- *
- * ChronoUnit.CENTURIES
- *
- * Unit that represents the concept of a century.
- * For the ISO calendar system, it is equal to 100 years.
- *
- * When used with other calendar systems it must correspond to an integral number of days
- * and is normally an integral number of years.
- *
- * ChronoUnit.MILLENNIA
- *
- * Unit that represents the concept of a millennium.
- * For the ISO calendar system, it is equal to 1000 years.
- *
- * When used with other calendar systems it must correspond to an integral number of days
- * and is normally an integral number of years.
- *
- * ChronoUnit.ERAS
- *
- * Unit that represents the concept of an era.
- * The ISO calendar system doesn't have eras thus it is impossible to add
- * an era to a date or date-time.
- * The estimated duration of the era is artificially defined as {Year.MAX_VALUE} + 1.
- *
- * When used with other calendar systems there are no restrictions on the unit.
- *
- * ChronoUnit.FOREVER
- *
- * Artificial unit that represents the concept of forever.
- * This is primarily used with {@link TemporalField} to represent unbounded fields
- * such as the year or era.
- * The estimated duration of the era is artificially defined as the largest duration
- * supported by {@link Duration}.
- *
+ * - `ChronoUnit.HOURS`: Unit that represents the concept of an hour. For the ISO calendar system,
+ * it is equal to 60 minutes.
+ * 
+ * - `ChronoUnit.MICROS`: Unit that represents the concept of a microsecond. For the ISO calendar
+ * system, it is equal to the 1,000,000th part of the second unit.
+ * 
+ * - `ChronoUnit.MILLENNIA`: Unit that represents the concept of a millennium. For the ISO calendar
+ * system, it is equal to 1,000 years.
+ * 
+ * - `ChronoUnit.MILLIS`: Unit that represents the concept of a millisecond. For the ISO calendar
+ * system, it is equal to the 1000th part of the second unit.
+ * 
+ * - `ChronoUnit.MINUTES`: Unit that represents the concept of a minute. For the ISO calendar system,
+ * it is equal to 60 seconds.
+ * 
+ * - `ChronoUnit.MONTHS`: Unit that represents the concept of a month. For the ISO calendar system,
+ * the length of the month varies by month-of-year. The estimated duration of a month is one twelfth
+ * of 365.2425 Days.
+ * 
+ * - `ChronoUnit.NANOS`: Unit that represents the concept of a nanosecond, the smallest supported unit
+ * of time. For the ISO calendar system, it is equal to the 1,000,000,000th part of the second unit.
+ * 
+ * - `ChronoUnit.SECONDS`: Unit that represents the concept of a second. For the ISO calendar system,
+ * it is equal to the second in the SI system of units, except around a leap-second.
+ * 
+ * - `ChronoUnit.WEEKS`: Unit that represents the concept of a week. For the ISO calendar system,
+ * it is equal to 7 Days.
+ * 
+ * - `ChronoUnit.YEARS`: Unit that represents the concept of a year. For the ISO calendar system, it
+ * is equal to 12 months. The estimated duration of a year is 365.2425 Days.
  */
@@ -156,8 +95,3 @@ export class ChronoUnit extends TemporalUnit {
     /**
-     * Gets the estimated duration of this unit in the ISO calendar system.
-     *
-     * All of the units in this class have an estimated duration.
-     * Days vary due to daylight saving time, while months have different lengths.
-     *
-     * @return {Duration} the estimated duration of this unit, not null
+     * @return {Duration} the duration of this unit, which may be an estimate.
      */
@@ -169,11 +103,3 @@ duration() {
     /**
-     * Checks if the duration of the unit is an estimate.
-     *
-     * All time units in this class are considered to be accurate, while all date
-     * units in this class are considered to be estimated.
-     *
-     * This definition ignores leap seconds, but considers that Days vary due to
-     * daylight saving time and months have different lengths.
-     *
-     * @return {boolean} true if the duration is estimated, false if accurate
+     * @return {boolean} `true` if the duration is estimated, `false` if accurate.
      */
@@ -186,5 +112,3 @@ isDurationEstimated() {
     /**
-     * Checks if this unit is a date unit.
-     *
-     * @return true if a date unit, false if a time unit
+     * @return {boolean} `true` if date unit, `false` if a time unit.
      */
@@ -198,3 +122,3 @@ isDateBased() {
      *
-     * @return true if a time unit, false if a date unit
+     * @return {boolean} `true` if time unit, `false` if a date unit.
      */
@@ -207,12 +131,4 @@ isTimeBased() {
     /**
-     * Checks if this unit is supported by the specified temporal object.
-     *
-     * This checks that the implementing date-time can add/subtract this unit.
-     * This can be used to avoid throwing an exception.
-     *
-     * This default implementation derives the value using
-     * {@link Temporal#plus}.
-     *
-     * @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.
      */
@@ -246,33 +162,6 @@ isSupportedBy(temporal) {
     /**
-     * Returns a copy of the specified temporal object with the specified period added.
-     *
-     * The period added is a multiple of this unit. For example, this method
-     * could be used to add "3 days" to a date by calling this method on the
-     * instance representing "days", passing the date and the period "3".
-     * The period to be added may be negative, which is equivalent to subtraction.
-     *
-     * There are two equivalent ways of using this method.
-     * The first is to invoke this method directly.
-     * The second is to use {@link Temporal#plus}:
-     * <pre>
-     *   // these two lines are equivalent, but the second approach is recommended
-     *   temporal = thisUnit.addTo(temporal);
-     *   temporal = temporal.plus(thisUnit);
-     * </pre>
-     * It is recommended to use the second approach, {@link plus},
-     * as it is a lot clearer to read in code.
-     *
-     * 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 an {@link UnsupportedTemporalTypeException} 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, not null
-     * @param {Number} amount  the amount of this unit to add, positive or negative
-     * @return {Temporal} the adjusted temporal object, not null
-     * @throws DateTimeException if the amount cannot be added
-     * @throws UnsupportedTemporalTypeException if the unit is not supported by the temporal
+     * @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.
      */
@@ -285,54 +174,8 @@ addTo(temporal, amount) {
     /**
-     * Calculates the amount of time between two temporal objects.
-     *
-     * This calculates the amount in terms of this unit. The start and end
-     * points are supplied as temporal objects and must be of compatible types.
-     * The implementation will convert the second type to be an instance of the
-     * first type before the calculating the amount.
-     * The result will be negative if the end is before the start.
-     * For example, the amount in hours between two temporal objects can be
-     * calculated using {@link HOURS.between}.
-     *
-     * The calculation returns a whole number, representing the number of
-     * complete units between the two temporals.
-     * For example, the amount 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 {@link Temporal#until}:
-     * <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>
-     *  daysBetween = DAYS.between(start, end);
-     *  // or alternatively
-     *  daysBetween = start.until(end, DAYS);
-     * </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 an {@link UnsupportedTemporalTypeException} must be thrown.
-     * Implementations must not alter the specified temporal objects.
-     *
-     * @implSpec
-     * Implementations must begin by checking to if the two temporals have the
-     * same type using `.constructor.name`. If they do not, then the result must be
-     * obtained by calling `temporal1.until`.
-     *
-     * @param {Temporal} temporal1  the base temporal object, not null
-     * @param {Temporal} temporal2  the other temporal object, exclusive, not null
-     * @return {Number} the amount of time between temporal1 and temporal2
-     *  in terms of this unit; positive if temporal2 is later than
-     *  temporal1, negative if earlier
-     * @throws DateTimeException if the amount cannot be calculated, or the end
-     *  temporal cannot be converted to the same type as the start temporal
-     * @throws UnsupportedTemporalTypeException if the unit is not supported by the temporal
-     * @throws ArithmeticException if numeric overflow occurs
+     * @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.
      */
@@ -349,8 +192,8 @@ between(temporal1, temporal2) {
     /**
-     * Compares this ChronoUnit to the specified {TemporalUnit}.
+     * Compares this ChronoUnit to the specified {@link TemporalUnit}.
      *
      * The comparison is based on the total length of the durations.
      *
-     * @param {TemporalUnit} other  the other unit to compare to, not null
-     * @return the comparator value, negative if less, positive if greater
+     * @param {!TemporalUnit} other the other unit to compare to.
+     * @return the comparator value, negative if less, positive if greater.
      */
@@ -357,0 +200,0 @@ compareTo(other) {

src/temporal/IsoFields.js

@@ -42,5 +42,5 @@ /*
  *
- * * {@link DAY_OF_QUARTER} - the day within the quarter, from 1 to 90, 91 or 92
- * * {@link QUARTER_OF_YEAR} - the week within the week-based-year
- * * {@link ChronoField#YEAR} - the standard ISO year
+ * * `IsoFields.DAY_OF_QUARTER` - the day within the quarter, from 1 to 90, 91 or 92
+ * * `QUARTER_OF_YEAR` - the week within the week-based-year
+ * * `ChronoField.YEAR` - the standard ISO year (see {@link ChronoField})
  *
@@ -55,6 +55,6 @@ * ### Week based years
  *
- * * {@link ChronoField#DAY_OF_WEEK} - the standard field defining the
- *   day-of-week from Monday (1) to Sunday (7)
- * * {@link WEEK_OF_WEEK_BASED_YEAR} - the week within the week-based-year
- * * {@link WEEK_BASED_YEAR} - the week-based-year
+ * * `ChronoField.DAY_OF_WEEK` - the standard field defining the
+ *   day-of-week from Monday (1) to Sunday (7) (see {@link ChronoField})
+ * * `WEEK_OF_WEEK_BASED_YEAR` - the week within the week-based-year
+ * * `WEEK_BASED_YEAR` - the week-based-year 
  *
@@ -86,8 +86,4 @@ * The week-based-year itself is defined relative to the standard ISO proleptic year.
  *
- * ### Static properties of Class {@link IsoFields}
+ * @property {TemporalField} DAY_OF_QUARTER The field that represents the day-of-quarter.
  *
- * IsoFields.DAY_OF_QUARTER
- *
- * The field that represents the day-of-quarter.
- *
  * This field allows the day-of-quarter value to be queried and set.
@@ -104,6 +100,4 @@ * The day-of-quarter has values from 1 to 90 in Q1 of a standard year, from 1 to 91
  *
- * IsoFields.QUARTER_OF_YEAR
+ * @property {TemporalField} QUARTER_OF_YEAR The field that represents the quarter-of-year.
  *
- * The field that represents the quarter-of-year.
- *
  * This field allows the quarter-of-year value to be queried and set.
@@ -114,18 +108,14 @@ * The quarter-of-year has values from 1 to 4.
  *
- * IsoFields.WEEK_OF_WEEK_BASED_YEAR
+ * @property {TemporalField} WEEK_OF_WEEK_BASED_YEAR The field that represents the
+ * week-of-week-based-year.
  *
- * The field that represents the week-of-week-based-year.
- *
  * This field allows the week of the week-based-year value to be queried and set.
  *
- * IsoFields.WEEK_BASED_YEAR
+ * @property {TemporalField} WEEK_BASED_YEAR The field that represents the week-based-year.
  *
- * The field that represents the week-based-year.
- *
  * This field allows the week-based-year value to be queried and set.
  *
- * IsoFields.WEEK_BASED_YEARS
+ * @property {TemporalField} WEEK_BASED_YEARS The unit that represents week-based-years for
+ * the purpose of addition and subtraction.
  *
- * The unit that represents week-based-years for the purpose of addition and subtraction.
- *
  * This allows a number of week-based-years to be added to, or subtracted from, a date.
@@ -140,10 +130,10 @@ * The unit is equal to either 52 or 53 weeks.
  *
- * IsoFields.QUARTER_YEARS
- *
- * Unit that represents the concept of a quarter-year.
+ * @property {TemporalField} QUARTER_YEARS Unit that represents the concept of a quarter-year.
  * For the ISO calendar system, it is equal to 3 months.
  * The estimated duration of a quarter-year is one quarter of 365.2425 days.
+ * 
+ * @typedef {Object} IsoFields
+ * @type {Object}
  */
-export class IsoFields {
-}
+export const IsoFields = {};
 
@@ -156,2 +146,3 @@ //-----------------------------------------------------------------------
  * Implementation of the field.
+ * @private
  */
@@ -262,3 +253,3 @@ class Field extends TemporalField{
      */
-    getDisplayName(/*locale*/) {
+    displayName(/*locale*/) {
         return this.toString();
@@ -281,3 +272,5 @@ }
 
-
+/**
+ * @private
+ */
 class DAY_OF_QUARTER_FIELD extends Field {
@@ -419,2 +412,5 @@
 
+/**
+ * @private
+ */
 class QUARTER_OF_YEAR_FIELD extends Field {
@@ -501,2 +497,5 @@
 
+/**
+ * @private
+ */
 class WEEK_OF_WEEK_BASED_YEAR_FIELD extends Field {
@@ -629,3 +628,3 @@
      */
-    getDisplayName() {
+    displayName() {
         return 'Week';
@@ -636,2 +635,5 @@ }
 
+/**
+ * @private
+ */
 class WEEK_BASED_YEAR_FIELD extends Field {
@@ -731,2 +733,3 @@
  * Implementation of the period unit.
+ * @private
  */
@@ -733,0 +736,0 @@ class Unit extends TemporalUnit {

src/temporal/TemporalField.js

@@ -0,1 +1,3 @@
+import { abstractMethodFail } from '../assert';
+
 /**
@@ -24,2 +26,224 @@ * @copyright (c) 2016, Philipp Thürwächter & Pattrick Hüper
  */
-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');
+    }
+}

src/temporal/TemporalUnit.js

@@ -35,3 +35,3 @@ /*
      * 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`.
      *
@@ -43,3 +43,3 @@ * Some units may return an accurate duration while others return an estimate.
      *
-     * @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.
      */
@@ -59,3 +59,3 @@ duration() {
      *
-     * @return {boolean} true if the duration is estimated, false if accurate
+     * @return {boolean} `true` if the duration is estimated, `false` if accurate.
      */
@@ -69,3 +69,3 @@ isDurationEstimated() {
      *
-     * @return {boolean} true if date-based
+     * @return {boolean} `true` if date unit, `false` if a time unit.
      */
@@ -79,3 +79,3 @@ isDateBased() {
      *
-     * @return {boolean} true if time-based
+     * @return {boolean} `true` if time unit, `false` if a date unit.
      */
@@ -93,4 +93,4 @@ isTimeBased() {
      *
-     * @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.
      */
@@ -129,6 +129,6 @@ // eslint-disable-next-line no-unused-vars
      *
-     * @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.
      */
@@ -151,3 +151,3 @@ // eslint-disable-next-line no-unused-vars
      * 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.
@@ -173,11 +173,11 @@ *
      * {@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.
      */
@@ -188,3 +188,2 @@ // eslint-disable-next-line no-unused-vars
     }
-
 }

src/temporal/ValueRange.js

@@ -118,2 +118,3 @@ /**
         }
+        return value;
     }
@@ -120,0 +121,0 @@

src/YearMonth.js

@@ -411,3 +411,3 @@ /*
      */
-    getLong( field) {
+    getLong(field) {
         requireNonNull(field, 'field');
@@ -536,18 +536,13 @@ requireInstance(field, TemporalField, 'field');
      * if called with 1 argument, then {@link YearMonth.withAdjuster} is executed,
+     * otherwise {@link YearMonth.withFieldValue} is executed.
      *
-     * if called with 2 arguments and first argument is an instance of TemporalField, then {@link YearMonth.withFieldValue} is executed,
-     *
-     * otherwise {@link YearMonth.withYearMonth} is executed
-     *
-     * @param {!(TemporalAdjuster|TemporalField|Number)} adjusterOrFieldOrNumber
+     * @param {!(TemporalAdjuster|TemporalField)} adjusterOrField
      * @param {?number} value nullable only of first argument is an instance of TemporalAdjuster
      * @returns {YearMonth}
      */
-    with(adjusterOrFieldOrNumber, value) {
+    with(adjusterOrField, value) {
         if (arguments.length === 1) {
-            return this.withAdjuster(adjusterOrFieldOrNumber);
-        } else if (arguments.length === 2 && adjusterOrFieldOrNumber instanceof TemporalField){
-            return this.withFieldValue(adjusterOrFieldOrNumber, value);
+            return this.withAdjuster(adjusterOrField);
         } else {
-            return this.withYearMonth(adjusterOrFieldOrNumber, value);
+            return this.withFieldValue(adjusterOrField, value);
         }
@@ -557,19 +552,2 @@ }
     /**
-     * Returns a copy of this year-month with the new year and month, checking
-     * to see if a new object is in fact required.
-     *
-     * @param {number} newYear  the year to represent, validated from MIN_YEAR to MAX_YEAR
-     * @param {number} newMonth  the month-of-year to represent, validated not null
-     * @return the year-month, not null
-     */
-    withYearMonth(newYear, newMonth) {
-        requireNonNull(newYear);
-        requireNonNull(newMonth);
-        if (this._year === newYear && this._month === newMonth) {
-            return this;
-        }
-        return new YearMonth(newYear, newMonth);
-    }
-
-    /**
      * Returns an adjusted copy of this year-month.
@@ -677,3 +655,3 @@ *
         ChronoField.YEAR.checkValidValue(year);
-        return this.withYearMonth(year, this._month);
+        return new YearMonth(year, this._month);
     }
@@ -692,3 +670,3 @@
         ChronoField.MONTH_OF_YEAR.checkValidValue(month);
-        return this.withYearMonth(this._year, month);
+        return new YearMonth(this._year, month);
     }
@@ -758,3 +736,3 @@
         const newYear = ChronoField.YEAR.checkValidIntValue(this._year + yearsToAdd);  // safe overflow
-        return this.withYearMonth(newYear, this._month);
+        return this.withYear(newYear);
     }
@@ -779,3 +757,3 @@
         const newMonth = MathUtil.floorMod(calcMonths, 12) + 1;
-        return this.withYearMonth(newYear, newMonth);
+        return new YearMonth(newYear, newMonth);
     }
@@ -782,0 +760,0 @@

No alert changes

Improved metrics

Total package byte prevSize

3973853

increased by7.61%

Number of package files

88

increased by2.33%

Lines of code

51212

increased by8.83%

No dependency changes