js-joda - npm Package Compare versions

Comparing version 0.2.4 to 0.2.5

package.json

 {
   "name": "js-joda",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "a date and time library for javascript",
@@ -5,0 +5,0 @@ "repository": {

src/_init.js

@@ -11,2 +11,3 @@ /*
 import {_init as LocalTimeInit} from './LocalTime';
+import {_init as LocalDateTimeInit} from './LocalDateTime';
 import {_init as MonthInit} from './Month';
@@ -41,2 +42,3 @@ import {_init as PeriodInit} from './Period';
     LocalDateInit();
+    LocalDateTimeInit();
     MonthInit();
@@ -43,0 +45,0 @@ PeriodInit();

src/chrono/ChronoLocalDate.js

@@ -0,1 +1,7 @@
+/*
+ * @copyright (c) 2016, Philipp Thuerwaechter & Pattrick Hueper
+ * @copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos
+ * @license BSD-3-Clause (see LICENSE in the root directory of this source tree)
+ */
+
 import {ChronoField} from '../temporal/ChronoField';
@@ -8,2 +14,163 @@ import {ChronoUnit} from '../temporal/ChronoUnit';
 
+/**
+ * A date without time-of-day or time-zone in an arbitrary chronology, intended
+ * for advanced globalization use cases.
+ * <p>
+ * <b>Most applications should declare method signatures, fields and variables
+ * as {@link LocalDate}, not this interface.</b>
+ * <p>
+ * A {@code ChronoLocalDate} is the abstract representation of a date where the
+ * {@code Chronology chronology}, or calendar system, is pluggable.
+ * The date is defined in terms of fields expressed by {@link TemporalField},
+ * where most common implementations are defined in {@link ChronoField}.
+ * The chronology defines how the calendar system operates and the meaning of
+ * the standard fields.
+ *
+ * <h4>When to use this interface</h4>
+ * The design of the API encourages the use of {@code LocalDate} rather than this
+ * interface, even in the case where the application needs to deal with multiple
+ * calendar systems. The rationale for this is explored in the following documentation.
+ * <p>
+ * The primary use case where this interface should be used is where the generic
+ * type parameter {@code <C>} is fully defined as a specific chronology.
+ * In that case, the assumptions of that chronology are known at development
+ * time and specified in the code.
+ * <p>
+ * When the chronology is defined in the generic type parameter as ? or otherwise
+ * unknown at development time, the rest of the discussion below applies.
+ * <p>
+ * To emphasize the point, declaring a method signature, field or variable as this
+ * interface type can initially seem like the sensible way to globalize an application,
+ * however it is usually the wrong approach.
+ * As such, it should be considered an application-wide architectural decision to choose
+ * to use this interface as opposed to {@code LocalDate}.
+ *
+ * <h4>Architectural issues to consider</h4>
+ * These are some of the points that must be considered before using this interface
+ * throughout an application.
+ * <p>
+ * 1) Applications using this interface, as opposed to using just {@code LocalDate},
+ * face a significantly higher probability of bugs. This is because the calendar system
+ * in use is not known at development time. A key cause of bugs is where the developer
+ * applies assumptions from their day-to-day knowledge of the ISO calendar system
+ * to code that is intended to deal with any arbitrary calendar system.
+ * The section below outlines how those assumptions can cause problems
+ * The primary mechanism for reducing this increased risk of bugs is a strong code review process.
+ * This should also be considered a extra cost in maintenance for the lifetime of the code.
+ * <p>
+ * 2) This interface does not enforce immutability of implementations.
+ * While the implementation notes indicate that all implementations must be immutable
+ * there is nothing in the code or type system to enforce this. Any method declared
+ * to accept a {@code ChronoLocalDate} could therefore be passed a poorly or
+ * maliciously written mutable implementation.
+ * <p>
+ * 3) Applications using this interface  must consider the impact of eras.
+ * {@code LocalDate} shields users from the concept of eras, by ensuring that {@code getYear()}
+ * returns the proleptic year. That decision ensures that developers can think of
+ * {@code LocalDate} instances as consisting of three fields - year, month-of-year and day-of-month.
+ * By contrast, users of this interface must think of dates as consisting of four fields -
+ * era, year-of-era, month-of-year and day-of-month. The extra era field is frequently
+ * forgotten, yet it is of vital importance to dates in an arbitrary calendar system.
+ * For example, in the Japanese calendar system, the era represents the reign of an Emperor.
+ * Whenever one reign ends and another starts, the year-of-era is reset to one.
+ * <p>
+ * 4) The only agreed international standard for passing a date between two systems
+ * is the ISO-8601 standard which requires the ISO calendar system. Using this interface
+ * throughout the application will inevitably lead to the requirement to pass the date
+ * across a network or component boundary, requiring an application specific protocol or format.
+ * <p>
+ * 5) Long term persistence, such as a database, will almost always only accept dates in the
+ * ISO-8601 calendar system (or the related Julian-Gregorian). Passing around dates in other
+ * calendar systems increases the complications of interacting with persistence.
+ * <p>
+ * 6) Most of the time, passing a {@code ChronoLocalDate} throughout an application
+ * is unnecessary, as discussed in the last section below.
+ *
+ * <h4>False assumptions causing bugs in multi-calendar system code</h4>
+ * As indicated above, there are many issues to consider when try to use and manipulate a
+ * date in an arbitrary calendar system. These are some of the key issues.
+ * <p>
+ * Code that queries the day-of-month and assumes that the value will never be more than
+ * 31 is invalid. Some calendar systems have more than 31 days in some months.
+ * <p>
+ * Code that adds 12 months to a date and assumes that a year has been added is invalid.
+ * Some calendar systems have a different number of months, such as 13 in the Coptic or Ethiopic.
+ * <p>
+ * Code that adds one month to a date and assumes that the month-of-year value will increase
+ * by one or wrap to the next year is invalid. Some calendar systems have a variable number
+ * of months in a year, such as the Hebrew.
+ * <p>
+ * Code that adds one month, then adds a second one month and assumes that the day-of-month
+ * will remain close to its original value is invalid. Some calendar systems have a large difference
+ * between the length of the longest month and the length of the shortest month.
+ * For example, the Coptic or Ethiopic have 12 months of 30 days and 1 month of 5 days.
+ * <p>
+ * Code that adds seven days and assumes that a week has been added is invalid.
+ * Some calendar systems have weeks of other than seven days, such as the French Revolutionary.
+ * <p>
+ * Code that assumes that because the year of {@code date1} is greater than the year of {@code date2}
+ * then {@code date1} is after {@code date2} is invalid. This is invalid for all calendar systems
+ * when referring to the year-of-era, and especially untrue of the Japanese calendar system
+ * where the year-of-era restarts with the reign of every new Emperor.
+ * <p>
+ * Code that treats month-of-year one and day-of-month one as the start of the year is invalid.
+ * Not all calendar systems start the year when the month value is one.
+ * <p>
+ * In general, manipulating a date, and even querying a date, is wide open to bugs when the
+ * calendar system is unknown at development time. This is why it is essential that code using
+ * this interface is subjected to additional code reviews. It is also why an architectural
+ * decision to avoid this interface type is usually the correct one.
+ *
+ * <h4>Using LocalDate instead</h4>
+ * The primary alternative to using this interface throughout your application is as follows.
+ * <p><ul>
+ * <li>Declare all method signatures referring to dates in terms of {@code LocalDate}.
+ * <li>Either store the chronology (calendar system) in the user profile or lookup
+ *  the chronology from the user locale
+ * <li>Convert the ISO {@code LocalDate} to and from the user's preferred calendar system during
+ *  printing and parsing
+ * </ul><p>
+ * This approach treats the problem of globalized calendar systems as a localization issue
+ * and confines it to the UI layer. This approach is in keeping with other localization
+ * issues in the java platform.
+ * <p>
+ * As discussed above, performing calculations on a date where the rules of the calendar system
+ * are pluggable requires skill and is not recommended.
+ * Fortunately, the need to perform calculations on a date in an arbitrary calendar system
+ * is extremely rare. For example, it is highly unlikely that the business rules of a library
+ * book rental scheme will allow rentals to be for one month, where meaning of the month
+ * is dependent on the user's preferred calendar system.
+ * <p>
+ * A key use case for calculations on a date in an arbitrary calendar system is producing
+ * a month-by-month calendar for display and user interaction. Again, this is a UI issue,
+ * and use of this interface solely within a few methods of the UI layer may be justified.
+ * <p>
+ * In any other part of the system, where a date must be manipulated in a calendar system
+ * other than ISO, the use case will generally specify the calendar system to use.
+ * For example, an application may need to calculate the next Islamic or Hebrew holiday
+ * which may require manipulating the date.
+ * This kind of use case can be handled as follows:
+ * <p><ul>
+ * <li>start from the ISO {@code LocalDate} being passed to the method
+ * <li>convert the date to the alternate calendar system, which for this use case is known
+ *  rather than arbitrary
+ * <li>perform the calculation
+ * <li>convert back to {@code LocalDate}
+ * </ul><p>
+ * Developers writing low-level frameworks or libraries should also avoid this interface.
+ * Instead, one of the two general purpose access interfaces should be used.
+ * Use {@link TemporalAccessor} if read-only access is required, or use {@link Temporal}
+ * if read-write access is required.
+ *
+ * <h3>Specification for implementors</h3>
+ * This interface must be implemented with care to ensure other classes operate correctly.
+ * All implementations that can be instantiated must be final, immutable and thread-safe.
+ * Subclasses should be Serializable wherever possible.
+ * <p>
+ * Additional calendar systems may be added to the system.
+ * See {@link Chronology} for more details.
+ * <p>
+ * In JDK 8, this is an interface with default methods.
+ * Since there are no default methods in JDK 7, an abstract class is used.
+ */
 export class ChronoLocalDate extends TemporalAccessor {
@@ -10,0 +177,0 @@

src/Clock.js

@@ -92,3 +92,3 @@ /**
      * @param zoneOffset  the zoneOffset to use as zone Offset, not null
-     * @return a clock that always returns the same instant, not null
+     * @return {Clock} a clock that always returns the same instant, not null
      */
@@ -95,0 +95,0 @@ static fixed(fixedInstant, zoneOffset) {

src/DayOfWeek.js

@@ -16,3 +16,4 @@ /*
 import {TemporalAccessor} from './temporal/TemporalAccessor';
-import {TemporalQueries, createTemporalQuery} from './temporal/TemporalQueries';
+import {TemporalQueries} from './temporal/TemporalQueries';
+import {createTemporalQuery} from './temporal/TemporalQuery';
 
@@ -19,0 +20,0 @@ export class DayOfWeek extends TemporalAccessor {

src/format/DateTimeFormatter.js

@@ -262,2 +262,3 @@ /**
 export function _init() {
+
     DateTimeFormatter.ISO_LOCAL_DATE = new DateTimeFormatterBuilder()
@@ -270,2 +271,21 @@ .appendValue(ChronoField.YEAR, 4, 10, SignStyle.EXCEEDS_PAD)
         .toFormatter(ResolverStyle.STRICT).withChronology(IsoChronology.INSTANCE);
+
+    DateTimeFormatter.ISO_LOCAL_TIME = new DateTimeFormatterBuilder()
+        .appendValue(ChronoField.HOUR_OF_DAY, 2)
+        .appendLiteral(':')
+        .appendValue(ChronoField.MINUTE_OF_HOUR, 2)
+        //.optionalStart()
+        .appendLiteral(':')
+        .appendValue(ChronoField.SECOND_OF_MINUTE, 2)
+        //.optionalStart()
+        //.appendFraction(ChronoField.NANO_OF_SECOND, 0, 9, true)
+        .toFormatter(ResolverStyle.STRICT);
+
+    DateTimeFormatter.ISO_LOCAL_DATE_TIME = new DateTimeFormatterBuilder()
+        .parseCaseInsensitive()
+        //.append(DateTimeFormatter.ISO_LOCAL_DATE)
+        .appendLiteral('T')
+        //.append(DateTimeFormatter.ISO_LOCAL_TIME)
+        .toFormatter(ResolverStyle.STRICT).withChronology(IsoChronology.INSTANCE);
+
 }

src/js-joda.js

@@ -11,2 +11,3 @@ /**
 export { LocalTime } from './LocalTime';
+export { LocalDateTime } from './LocalDateTime';
 export { MathUtil } from './MathUtil';
@@ -13,0 +14,0 @@ export { Month } from './Month';

src/LocalDate.js

@@ -15,3 +15,4 @@ /**
 import {ChronoLocalDate} from './chrono/ChronoLocalDate';
-import {TemporalQueries, createTemporalQuery} from './temporal/TemporalQueries';
+import {TemporalQueries} from './temporal/TemporalQueries';
+import {createTemporalQuery} from './temporal/TemporalQuery';
 import {DateTimeFormatter} from './format/DateTimeFormatter';
@@ -31,8 +32,7 @@
 
-
-  /**
-   * The number of days from year zero to year 1970.
-   * There are five 400 year cycles from year zero to 2000.
-   * There are 7 leap years from 1970 to 2000.
-   */
+/**
+* The number of days from year zero to year 1970.
+* There are five 400 year cycles from year zero to 2000.
+* There are 7 leap years from 1970 to 2000.
+*/
 const  DAYS_0000_TO_1970 = (DAYS_PER_CYCLE * 5) - (30 * 365 + 7);
@@ -70,4 +70,4 @@
      *
-     * @param clock  the clock to use, if null, the system clock and default time-zone is used.
-     * @return the current date, not null
+     * @param {Clock} clock  the clock to use, if null, the system clock and default time-zone is used.
+     * @return {LocalDate} the current date, not null
      */
@@ -530,4 +530,3 @@ static now(clock = Clock.systemDefaultZone()) {
     _withTemporalAdjuster(adjuster) {
-        assert(adjuster != null, 'adjuster', NullPointerException);
-        assert(typeof adjuster.adjustInto === 'function', adjuster + 'is mot an adjuster', IllegalArgumentException);
+        requireNonNull(adjuster, 'adjuster');
         // optimizations
@@ -537,2 +536,3 @@ if (adjuster instanceof LocalDate) {
         }
+        assert(typeof adjuster.adjustInto === 'function', 'adjuster', IllegalArgumentException);
         return adjuster.adjustInto(this);
@@ -539,0 +539,0 @@ }

src/LocalTime.js

@@ -19,3 +19,4 @@ /**
 import {TemporalAccessor} from './temporal/TemporalAccessor';
-import {TemporalQueries, createTemporalQuery} from './temporal/TemporalQueries';
+import {TemporalQueries} from './temporal/TemporalQueries';
+import {createTemporalQuery} from './temporal/TemporalQuery';
 
@@ -145,4 +146,3 @@ /**
         if (time == null) {
-            throw new DateTimeException('Unable to obtain LocalTime from TemporalAccessor: ' +
-                    temporal + ', type ' + temporal);
+            throw new DateTimeException(`Unable to obtain LocalTime TemporalAccessor: ${temporal}, type ${temporal.constructor != null ? temporal.constructor.name : ''}`);
         }
@@ -388,3 +388,3 @@ return time;
         if(arguments.length < 2){
-            return this._with1.apply(this, arguments);
+            return this._withTemporalAdjuster.apply(this, arguments);
         } else {
@@ -416,3 +416,3 @@ return this._with2.apply(this, arguments);
      */
-    _with1(adjuster) {
+    _withTemporalAdjuster(adjuster) {
         requireNonNull(adjuster, 'adjuster');
@@ -419,0 +419,0 @@ // optimizations

src/temporal/ChronoField.js

@@ -49,17 +49,17 @@ /**
      *
-     * @return true if it is a component of a date
+     * @return {boolean} true if it is a component of a date
      */
     isDateBased() {
         var dateBased =
-            //this === ChronoField.DAY_OF_WEEK ||
-            //this === ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH ||
-            //this === ChronoField.ALIGNED_DAY_OF_WEEK_IN_YEAR ||
+            this === ChronoField.DAY_OF_WEEK ||
+            this === ChronoField.ALIGNED_DAY_OF_WEEK_IN_MONTH ||
+            this === ChronoField.ALIGNED_DAY_OF_WEEK_IN_YEAR ||
             this === ChronoField.DAY_OF_MONTH ||
             this === ChronoField.DAY_OF_YEAR ||
             this === ChronoField.EPOCH_DAY ||
-            //this === ChronoField.ALIGNED_WEEK_OF_MONTH ||
-            //this === ChronoField.ALIGNED_WEEK_OF_YEAR ||
+            this === ChronoField.ALIGNED_WEEK_OF_MONTH ||
+            this === ChronoField.ALIGNED_WEEK_OF_YEAR ||
             this === ChronoField.MONTH_OF_YEAR ||
             //this === ChronoField.EPOCH_MONTH ||
-            //this === ChronoField.YEAR_OF_ERA ||
+            this === ChronoField.YEAR_OF_ERA ||
             this === ChronoField.YEAR ||
@@ -71,2 +71,27 @@ this === ChronoField.ERA;
     /**
+     * Checks if this field represents a component of a time.
+     *
+     * @return {boolean} true if it is a component of a time
+     */
+    isTimeBased() {
+        var timeBased =
+            this === ChronoField.NANO_OF_SECOND     ||
+            this === ChronoField.NANO_OF_DAY        ||
+            this === ChronoField.MICRO_OF_SECOND    ||
+            this === ChronoField.MICRO_OF_DAY       ||
+            this === ChronoField.MILLI_OF_SECOND    ||
+            this === ChronoField.MILLI_OF_DAY       ||
+            this === ChronoField.SECOND_OF_MINUTE   ||
+            this === ChronoField.SECOND_OF_DAY      ||
+            this === ChronoField.MINUTE_OF_HOUR     ||
+            this === ChronoField.MINUTE_OF_DAY      ||
+            this === ChronoField.HOUR_OF_AMPM       ||
+            this === ChronoField.CLOCK_HOUR_OF_AMPM ||
+            this === ChronoField.HOUR_OF_DAY        ||
+            this === ChronoField.CLOCK_HOUR_OF_DAY  ||
+            this === ChronoField.AMPM_OF_DAY;
+        return timeBased;
+    }
+
+    /**
      * Get the range of valid values for this field using the temporal object to
@@ -73,0 +98,0 @@ * refine the result.

src/temporal/TemporalQueries.js

@@ -7,5 +7,4 @@ /**
 
-import {Enum} from '../Enum';
-
 import {ChronoField} from './ChronoField';
+import {createTemporalQuery} from './TemporalQuery';
 
@@ -110,3 +109,3 @@ import {LocalDate} from '../LocalDate';
      *
-     * @return a query that can obtain the chronology of a temporal, not null
+     * @return {TemporalQuery} a query that can obtain the chronology of a temporal, not null
      */
@@ -233,16 +232,2 @@ static chronology() {
 
-/** 
- * Factory to create something similar to the JSR-310 {TemporalQuery} interface, takes a function and returns a new TemporalQuery object that presents that function
- * as the queryFrom() function.
- * TODO: maybe should be moved to a separate file?
- * @param name
- * @param queryFromFunction
- */
-export function createTemporalQuery(name, queryFromFunction) {
-    class TemporalQuery extends Enum {
-    }
-    TemporalQuery.prototype.queryFrom = queryFromFunction;   
-    return new TemporalQuery(name);
-}
-
 export function _init() {
@@ -249,0 +234,0 @@ //-----------------------------------------------------------------------

test.js

@@ -1,60 +0,92 @@
-/*
- * @copyright (c) 2016, Philipp Thuerwaechter & Pattrick Hueper
- * @copyright (c) 2007-present, Stephen Colebourne & Michael Nascimento Santos
- * @license BSD-3-Clause (see LICENSE in the root directory of this source tree)
- */
+var createLoops = 50000;
+var accessLoops = 50;
 
-function Foo(){
-    this._map = {};
-    return this;
+console.log('################### START ########################');
+
+function now(){ return new Date().getTime(); }
+
+function measureIt(n, f){
+    var t, i;
+    console.log('########', n, '##########');
+    t = now();
+    for(i=0; i<createLoops; i++){ f(); }
+    console.log('########', n, now()-t, 'ms', createLoops, 'createLoops', accessLoops, 'accessLoops');
 }
 
-Foo.prototype.add = function(key, val){
-    this._map[key] = val;
+var sumFunc = function() {
+    return this.a + this.b + this.c;
 };
 
-/*
+function doSomeThing(o){
+    var i, sum = 0;
+    for(i=0; i<accessLoops; i++) { sum += o.sum();}
+    return sum;
+}
 
-var i;
-var a = {};
-for(i=0; i<10000; i++){
-    var f = new Foo();
-    f.add(a, i);
+// -------------------------------------------------------
+
+function Immutable(i) {
+    this.a = i + 1;
+    this.b = i + 2;
+    this.c = i + 3;
+    Object.freeze(this);
 }
-*/
 
+Immutable.prototype.sum = sumFunc;
 
-var g = Object.create(Foo.prototype);
-g._map = {};
+measureIt('Immutable', function(){
+    return doSomeThing(new Immutable(7));
+});
 
-g.add('a',1);
+// -------------------------------------------------------
 
-
-function _classCallCheck(instance, Constructor) {
-    if (!(instance instanceof Constructor)) {
-        throw new TypeError("Cannot call a class as a function");
-    }
+function Mutable(i) {
+    this.a = i + 1;
+    this.b = i + 2;
+    this.c = i + 3;
 }
 
-function _possibleConstructorReturn(self, call) {
-    if (!self) {
-        throw new ReferenceError("this hasn't been initialised - super() hasn't been called");
-    }
-    return call && (typeof call === "object" || typeof call === "function") ? call : self;
+Mutable.prototype.sum = sumFunc;
+
+measureIt('Mutable', function(){
+    return doSomeThing(new Mutable(5));
+});
+
+// -------------------------------------------------------
+
+measureIt('Mutable.and.Freeze', function(){
+    var o = new Mutable(13);
+    Object.freeze(o);
+    return doSomeThing(o);
+});
+
+// -------------------------------------------------------
+
+function Immutable2(i) {
+    Object.defineProperties(this,{
+        a: { value: i+1, writable: false },
+        b: { value: i+2, writable: false },
+        c: { value: i+3, writable: false }
+    });
 }
 
-function _inherits(subClass, superClass) {
-    if (typeof superClass !== "function" && superClass !== null) {
-        throw new TypeError("Super expression must either be null or a function, not " + typeof superClass);
-    }
-    subClass.prototype = Object.create(superClass && superClass.prototype, {
-        constructor: {
-            value: subClass,
-            enumerable: false,
-            writable: true,
-            configurable: true
-        }
+Immutable2.prototype.sum = sumFunc;
+
+measureIt('ImmutableByObjectDefineProperties', function(){
+    return doSomeThing(new Immutable2(7));
+});
+
+// -------------------------------------------------------
+
+function createImmutable(i){
+    return Object.create({},{
+        a: { value: i+1, writable: false },
+        b: { value: i+2, writable: false },
+        c: { value: i+3, writable: false },
+        sum: { value: sumFunc, writable: false}
     });
-    if (superClass) Object.setPrototypeOf ? Object.setPrototypeOf(subClass, superClass) : subClass.__proto__ = superClass;
 }
 
+measureIt('Object.create', function(){
+    return doSomeThing(createImmutable(5));
+});

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Unidentified License

License

(Experimental) Something that seems like a license was found, but its contents could not be matched with a known license.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Unidentified License

License

(Experimental) Something that seems like a license was found, but its contents could not be matched with a known license.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

1718586

increased by0.83%

Number of package files

52

increased by8.33%

Worsened metrics

Lines of code

18704

decreased by-11.17%

No dependency changes