qrono 1.1.3 → 1.2.0

package/src/helpers.js

@@ -28,14 +28,6 @@ export const millisecondsPerHour = secondsPerHour * millisecondsPerSecond
 export const millisecondsPerDay = secondsPerDay * millisecondsPerSecond
 export const millisecondsPerWeek = secondsPerWeek * millisecondsPerSecond
 
-export const monday = 1
-export const tuesday = 2
-export const wednesday = 3
-export const thursday = 4
-export const friday = 5
-export const saturday = 6
-export const sunday = 7
-
 export function has(object, ...keys) {
   return keys.flat().some(object.hasOwnProperty, object)
 }
@@ -85,67 +77,3 @@ export function hasDatetimeField(object) {
     'millisecond',
   ])
 }
-
-/**
- * Resolve a local time that falls on or near a DST transition boundary.
- *
- * Handles two distinct cases that arise when constructing a local Date:
- *
- * GAP (spring-forward, isGap = true):
- *   A range of local times is skipped entirely. JavaScript automatically advances
- *   the time to the next valid moment (post-transition / DST side), adding the gap
- *   size to the UTC timestamp. The caller detects a gap by comparing the constructed
- *   Date's local fields against the originally requested values.
- *   - interpretAsDst = true  → accept JS's forward-shift as-is (DST side)
- *   - interpretAsDst = false → shift UTC back by the gap size (pre-transition side)
- *
- * OVERLAP (fall-back, isGap = false):
- *   A range of local times occurs twice. JavaScript always picks the DST side
- *   (first occurrence). If the time is not actually in an overlap, the adjustment
- *   will not preserve the original local fields and the original Date is returned.
- *   - interpretAsDst = true  → accept JS's DST-side interpretation as-is
- *   - interpretAsDst = false → shift UTC by the offset difference (standard-time side)
- *
- * In both cases the UTC adjustment uses the same formula:
- *   adjustedUTC = date.getTime() + adjust * millisecondsPerMinute
- * where adjust = nextDay.timezoneOffset - prevDay.timezoneOffset.
- * For a gap  the adjust is negative (offsets decrease going forward),
- * so subtracting it moves UTC backward to the pre-transition side.
- * For an overlap the adjust is also negative in the same direction,
- * and the same subtraction moves to the standard-time side.
- *
- * @param {boolean} interpretAsDst
- * @param {Date}    date  - The Date constructed from the requested local fields.
- * @param {boolean} isGap - true if the requested time fell in a DST gap (spring-forward).
- * @returns {Date}
- */
-export function resolveDstTime(interpretAsDst, date, isGap) {
-  const numeric = date.getTime()
-  const original = new Date(numeric)
-  if (interpretAsDst) {
-    return original
-  }
-  const nextDay = new Date(numeric)
-  nextDay.setDate(date.getDate() + 1)
-  const prevDay = new Date(numeric)
-  prevDay.setDate(date.getDate() - 1)
-  const adjust = nextDay.getTimezoneOffset() - prevDay.getTimezoneOffset()
-  if (adjust === 0) {
-    return original
-  }
-  const adjustedUTC = new Date(
-    new Date(numeric).setUTCMinutes(date.getUTCMinutes() + adjust)
-  )
-  if (isGap) {
-    return adjustedUTC
-  }
-  // For an overlap, verify the candidate preserves the original local fields.
-  // If it does not, the time is not actually in an overlap — return as-is.
-  if (
-    adjustedUTC.getHours() !== date.getHours() ||
-    adjustedUTC.getMinutes() !== date.getMinutes()
-  ) {
-    return original
-  }
-  return adjustedUTC
-}

package/src/qrono.js

@@ -6,7 +6,6 @@ import {
   isObject,
   isString,
   isValidDate,
-  resolveDstTime,
   hasDatetimeField,
   initialSafeDate,
   daysPerWeek,
@@ -14,13 +13,6 @@ import {
   minutesPerHour,
   millisecondsPerMinute,
   millisecondsPerDay,
-  monday,
-  tuesday,
-  wednesday,
-  thursday,
-  friday,
-  saturday,
-  sunday,
 } from './helpers.js'
 
 // -----------------------------------------------------------------------------
@@ -30,16 +22,6 @@ const qrono = Qrono
 
 export { qrono }
 
-export {
-  monday,
-  tuesday,
-  wednesday,
-  thursday,
-  friday,
-  saturday,
-  sunday,
-} from './helpers'
-
 // -----------------------------------------------------------------------------
 // Static
 // -----------------------------------------------------------------------------
@@ -48,7 +30,7 @@ Qrono.date = QronoDate
 // NOTE Must be flat object for shallow cloning.
 const defaultContext = {
   localtime: false,
-  interpretAsDst: true,
+  disambiguation: 'compatible',
 }
 
 for (const key of fields(defaultContext)) {
@@ -84,6 +66,14 @@ Qrono.asLocaltime = function () {
   return this
 }
 
+const monday = 1
+const tuesday = 2
+const wednesday = 3
+const thursday = 4
+const friday = 5
+const saturday = 6
+const sunday = 7
+
 Object.assign(Qrono, {
   monday,
   tuesday,
@@ -97,7 +87,7 @@ Object.assign(Qrono, {
 // -----------------------------------------------------------------------------
 // Constructor
 // -----------------------------------------------------------------------------
-const internal = Symbol('Qrono.internal')
+const internal = Symbol()
 
 function Qrono(...args) {
   if (!new.target) {
@@ -107,7 +97,7 @@ function Qrono(...args) {
     // properties
     nativeDate: null,
     localtime: false,
-    interpretAsDst: false,
+    disambiguation: 'compatible',
     // methods
     set,
     parse,
@@ -147,8 +137,9 @@ function Qrono(...args) {
   } else if (Number.isFinite(first) && !Number.isFinite(second)) {
     self.nativeDate = new Date(first)
   } else if (Number.isFinite(first) || Array.isArray(first)) {
-    const values = args.flat().filter(v => Number.isSafeInteger(v))
-    if (values.length !== args.flat().length) {
+    const flat = args.flat()
+    const values = flat.filter(v => Number.isSafeInteger(v))
+    if (values.length !== flat.length) {
       throw RangeError('Should be safe integers')
     }
     if (values.length > 7) {
@@ -195,43 +186,7 @@ function getNative(name) {
 function set(values) {
   const args = { ...values }
   args.month = args.month && args.month - 1
-  if (this.localtime) {
-    const dateOnly = !has(values, 'hour', 'minute', 'second', 'millisecond')
-    const interpretAsDst = dateOnly ? true : this.interpretAsDst
-    const baseDate = this.nativeDate ?? new Date(0, 0)
-    const newDate = new Date(initialSafeDate.getTime())
-    const requested = {
-      year: args.year ?? baseDate.getFullYear(),
-      month: args.month ?? baseDate.getMonth(),
-      day: args.day ?? baseDate.getDate(),
-      hour: args.hour ?? (dateOnly ? 0 : baseDate.getHours()),
-      minute: args.minute ?? (dateOnly ? 0 : baseDate.getMinutes()),
-      second: args.second ?? (dateOnly ? 0 : baseDate.getSeconds()),
-      millisecond:
-        args.millisecond ?? (dateOnly ? 0 : baseDate.getMilliseconds()),
-    }
-    newDate.setFullYear(requested.year, requested.month, requested.day)
-    newDate.setHours(
-      requested.hour,
-      requested.minute,
-      requested.second,
-      requested.millisecond
-    )
-    // Detect whether the constructed Date landed in a DST gap (missing time).
-    // In a gap, JavaScript silently shifts the time forward.
-    const isGap =
-      requested.year * 1e8 +
-        requested.month * 1e6 +
-        requested.day * 1e4 +
-        requested.hour * 1e2 +
-        requested.minute <
-      newDate.getFullYear() * 1e8 +
-        newDate.getMonth() * 1e6 +
-        newDate.getDate() * 1e4 +
-        newDate.getHours() * 1e2 +
-        newDate.getMinutes()
-    this.nativeDate = resolveDstTime(interpretAsDst, newDate, isGap)
-  } else {
+  if (!this.localtime) {
     const baseDate = this.nativeDate ?? new Date(0)
     const newDate = new Date(0)
     newDate.setUTCFullYear(
@@ -246,7 +201,71 @@ function set(values) {
       args.millisecond ?? baseDate.getUTCMilliseconds()
     )
     this.nativeDate = newDate
+    return this
+  }
+  const dateOnly = !has(values, 'hour', 'minute', 'second', 'millisecond')
+  const disambig = dateOnly ? 'later' : this.disambiguation
+  const baseDate = this.nativeDate ?? new Date(0, 0)
+  const newDate = new Date(initialSafeDate.getTime())
+  const requested = {
+    year: args.year ?? baseDate.getFullYear(),
+    month: args.month ?? baseDate.getMonth(),
+    day: args.day ?? baseDate.getDate(),
+    hour: args.hour ?? (dateOnly ? 0 : baseDate.getHours()),
+    minute: args.minute ?? (dateOnly ? 0 : baseDate.getMinutes()),
+    second: args.second ?? (dateOnly ? 0 : baseDate.getSeconds()),
+    millisecond:
+      args.millisecond ?? (dateOnly ? 0 : baseDate.getMilliseconds()),
+  }
+  newDate.setFullYear(requested.year, requested.month, requested.day)
+  newDate.setHours(
+    requested.hour,
+    requested.minute,
+    requested.second,
+    requested.millisecond
+  )
+  // Compute the offset-delta between the day before and after.
+  const numeric = newDate.getTime()
+  const nextDay = new Date(numeric)
+  nextDay.setDate(newDate.getDate() + 1)
+  const prevDay = new Date(numeric)
+  prevDay.setDate(newDate.getDate() - 1)
+  const adjust = nextDay.getTimezoneOffset() - prevDay.getTimezoneOffset()
+  // No DST transition nearby — nothing to resolve.
+  if (disambig === 'compatible' || adjust === 0) {
+    this.nativeDate = newDate
+    return this
+  }
+  // Detect whether the constructed Date landed in a DST gap (missing time).
+  // In a gap, JavaScript silently shifts the time forward.
+  const isGap =
+    requested.year * 1e8 +
+      requested.month * 1e6 +
+      requested.day * 1e4 +
+      requested.hour * 1e2 +
+      requested.minute <
+    newDate.getFullYear() * 1e8 +
+      newDate.getMonth() * 1e6 +
+      newDate.getDate() * 1e4 +
+      newDate.getHours() * 1e2 +
+      newDate.getMinutes()
+  // Compute the standard-time candidate.
+  // Verify the candidate actually preserves the original local fields.
+  // If it doesn't, the time isn't truly in an overlap.
+  const adjustedUTC = new Date(
+    new Date(numeric).setUTCMinutes(newDate.getUTCMinutes() + adjust)
+  )
+  const isOverlap =
+    adjustedUTC.getHours() === newDate.getHours() &&
+    adjustedUTC.getMinutes() === newDate.getMinutes()
+  if (!isGap && !isOverlap) {
+    this.nativeDate = newDate
+    return this
   }
+  if (disambig === 'reject') {
+    throw new RangeError(`Requested local time ${requested} is ambiguous.`)
+  }
+  this.nativeDate = disambig === 'later' ? newDate : adjustedUTC
   return this
 }
 
@@ -303,24 +322,26 @@ function parse(str) {
 // -----------------------------------------------------------------------------
 // Public methods
 // -----------------------------------------------------------------------------
+const p = (v, n) => String(v).padStart(n, '0')
+
 // Basic
 Qrono.prototype.toString = function () {
   if (this[internal].localtime) {
     const t = this[internal].nativeDate
     const offset = -t.getTimezoneOffset()
     const offsetAbs = Math.abs(offset)
-    return `${String(t.getFullYear()).padStart(4, '0')}-${String(
-      t.getMonth() + 1
-    ).padStart(2, '0')}-${String(t.getDate()).padStart(2, '0')}T${String(
-      t.getHours()
-    ).padStart(2, '0')}:${String(t.getMinutes()).padStart(2, '0')}:${String(
-      t.getSeconds()
-    ).padStart(2, '0')}.${String(t.getMilliseconds()).padStart(3, '0')}${
-      (offset >= 0 ? '+' : '-') +
-      String(Math.trunc(offsetAbs / minutesPerHour)).padStart(2, '0') +
-      ':' +
-      String(offsetAbs % minutesPerHour).padStart(2, '0')
-    }`
+    return (
+      `${p(t.getFullYear(), 4)}-` +
+      `${p(t.getMonth() + 1, 2)}-` +
+      `${p(t.getDate(), 2)}T` +
+      `${p(t.getHours(), 2)}:` +
+      `${p(t.getMinutes(), 2)}:` +
+      `${p(t.getSeconds(), 2)}.` +
+      `${p(t.getMilliseconds(), 3)}` +
+      `${offset >= 0 ? '+' : '-'}` +
+      `${p(Math.trunc(offsetAbs / minutesPerHour), 2)}:` +
+      `${p(offsetAbs % minutesPerHour, 2)}`
+    )
   }
   return this[internal].nativeDate.toISOString()
 }
@@ -338,7 +359,7 @@ Qrono.prototype.context = function (context) {
     ? this.clone(context)
     : {
         localtime: this[internal].localtime,
-        interpretAsDst: this[internal].interpretAsDst,
+        disambiguation: this[internal].disambiguation,
       }
 }
 
@@ -356,10 +377,10 @@ Qrono.prototype.localtime = function (arg) {
   return given(arg) ? this.clone({ localtime: arg }) : this[internal].localtime
 }
 
-Qrono.prototype.interpretAsDst = function (arg) {
+Qrono.prototype.disambiguation = function (arg) {
   return given(arg)
-    ? this.clone({ interpretAsDst: arg })
-    : this[internal].interpretAsDst
+    ? this.clone({ disambiguation: arg })
+    : this[internal].disambiguation
 }
 
 Qrono.prototype.valid = function () {
@@ -409,46 +430,20 @@ Qrono.prototype.asLocaltime = function () {
 }
 
 // Accessor
-Qrono.prototype.year = function (value) {
-  return given(value)
-    ? this.clone({ year: value })
-    : this[internal].getNative('FullYear')
-}
-
-Qrono.prototype.month = function (value) {
-  return given(value)
-    ? this.clone({ month: value })
-    : this[internal].getNative('Month') + 1
-}
-
-Qrono.prototype.day = function (value) {
-  return given(value)
-    ? this.clone({ day: value })
-    : this[internal].getNative('Date')
-}
-
-Qrono.prototype.hour = function (value) {
-  return given(value)
-    ? this.clone({ hour: value })
-    : this[internal].getNative('Hours')
-}
-
-Qrono.prototype.minute = function (value) {
-  return given(value)
-    ? this.clone({ minute: value })
-    : this[internal].getNative('Minutes')
-}
-
-Qrono.prototype.second = function (value) {
-  return given(value)
-    ? this.clone({ second: value })
-    : this[internal].getNative('Seconds')
-}
-
-Qrono.prototype.millisecond = function (value) {
-  return given(value)
-    ? this.clone({ millisecond: value })
-    : this[internal].getNative('Milliseconds')
+for (const [field, native, offset] of [
+  ['year', 'FullYear', 0],
+  ['month', 'Month', 1],
+  ['day', 'Date', 0],
+  ['hour', 'Hours', 0],
+  ['minute', 'Minutes', 0],
+  ['second', 'Seconds', 0],
+  ['millisecond', 'Milliseconds', 0],
+]) {
+  Qrono.prototype[field] = function (value) {
+    return given(value)
+      ? this.clone({ [field]: value })
+      : this[internal].getNative(native) + offset
+  }
 }
 
 // Getter
@@ -517,7 +512,7 @@ Qrono.prototype.minutesInDay = function () {
   if (!this[internal].localtime) {
     return minutesPerDay
   }
-  const startOfDay = this.context({ interpretAsDst: true }).startOfDay()
+  const startOfDay = this.context({ disambiguation: 'later' }).startOfDay()
   const nextDay = startOfDay.plus({ day: 1 }).startOfDay()
   if (startOfDay.day() === nextDay.day()) {
     return minutesPerDay
@@ -547,41 +542,26 @@ Qrono.prototype.weeksInYear = function () {
   return 52
 }
 
-Qrono.prototype.startOfYear = function () {
-  return this.clone({
-    month: 1,
-    day: 1,
-    hour: 0,
-    minute: 0,
-    second: 0,
-    millisecond: 0,
-  })
-}
-
-Qrono.prototype.startOfMonth = function () {
-  return this.clone({ day: 1, hour: 0, minute: 0, second: 0, millisecond: 0 })
+for (const [name, cloneArg] of [
+  ['Year', { month: 1, day: 1, hour: 0, minute: 0, second: 0, millisecond: 0 }],
+  ['Month', { day: 1, hour: 0, minute: 0, second: 0, millisecond: 0 }],
+  ['Hour', { minute: 0, second: 0, millisecond: 0 }],
+  ['Minute', { second: 0, millisecond: 0 }],
+  ['Second', { millisecond: 0 }],
+]) {
+  Qrono.prototype[`startOf${name}`] = function () {
+    return this.clone(cloneArg)
+  }
 }
 
 Qrono.prototype.startOfDay = function () {
   const timestamp = this.clone(
-    { interpretAsDst: true },
+    { disambiguation: 'later' },
     { hour: 0, minute: 0, second: 0, millisecond: 0 }
   ).numeric()
   return this.clone(timestamp)
 }
 
-Qrono.prototype.startOfHour = function () {
-  return this.clone({ minute: 0, second: 0, millisecond: 0 })
-}
-
-Qrono.prototype.startOfMinute = function () {
-  return this.clone({ second: 0, millisecond: 0 })
-}
-
-Qrono.prototype.startOfSecond = function () {
-  return this.clone({ millisecond: 0 })
-}
-
 Qrono.prototype.isSame = function (another) {
   return +this === +another
 }
@@ -626,8 +606,9 @@ function plus(sign, ...args) {
     }
     timeFields = arg0
   } else if (Number.isFinite(arg0) || Array.isArray(arg0)) {
-    const values = args.flat().filter(v => Number.isSafeInteger(v))
-    if (values.length !== args.flat().length) {
+    const flat = args.flat()
+    const values = flat.filter(v => Number.isSafeInteger(v))
+    if (values.length !== flat.length) {
       throw RangeError('Should be safe integers')
     }
     if (values.length > 7) {
@@ -681,7 +662,7 @@ function plus(sign, ...args) {
 // -----------------------------------------------------------------------------
 // QronoDate Class
 // -----------------------------------------------------------------------------
-const internalDate = Symbol('QronoDate.internal')
+const internalDate = Symbol()
 
 function QronoDate(...args) {
   if (!new.target) {
@@ -781,7 +762,7 @@ for (const method of [
 for (const method of ['minutesInDay', 'hasDstInYear', 'isDstTransitionDay']) {
   QronoDate.prototype[method] = function () {
     return qrono(
-      { interpretAsDst: true },
+      { disambiguation: 'later' },
       this[internalDate].datetime.toArray().slice(0, 3)
     )[method]()
   }

package/types/qrono.d.ts

@@ -230,16 +230,16 @@ declare namespace qrono {
   export function localtime(value: boolean): typeof qrono
 
   /**
-   * Returns whether interpretAsDst is enabled.
+   * Returns the current global disambiguation option.
    */
-  export function interpretAsDst(): boolean
+  export function disambiguation(): Disambiguation
 
   /**
-   * Sets whether interpretAsDst is enabled.
-   * @param value - True to enable interpretAsDst.
+   * Sets the global disambiguation option.
+   * @param value - The disambiguation option to set.
    * @returns The qrono object.
    */
-  export function interpretAsDst(value: boolean): typeof qrono
+  export function disambiguation(value: Disambiguation): typeof qrono
 
   /**
    * Returns new qrono instance with UTC context.
@@ -251,9 +251,20 @@ declare namespace qrono {
    */
   export function asLocaltime(): typeof qrono
 
+  /**
+   * The four disambiguation options for resolving ambiguous local times,
+   * mirroring the Temporal API.
+   *
+   * - `'compatible'`: Gap → later (JS native forward-shift). Overlap → earlier (standard-time side).
+   * - `'earlier'`:    Gap or overlap → the earlier (standard-time / pre-transition) instant.
+   * - `'later'`:      Gap or overlap → the later (DST side / post-transition) instant.
+   * - `'reject'`:     Throws `RangeError` if the time falls in a gap or overlap.
+   */
+  export type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject'
+
   export type Context = {
     localtime?: boolean
-    interpretAsDst?: boolean
+    disambiguation?: Disambiguation
   }
 
   export type TimeFields = {
@@ -322,16 +333,16 @@ declare namespace qrono {
     localtime(yes: boolean): Qrono
 
     /**
-     * Returns whether interpretAsDst is enabled for the Qrono instance.
+     * Returns the current disambiguation option of the Qrono instance.
      */
-    interpretAsDst(): boolean
+    disambiguation(): Disambiguation
 
     /**
-     * Sets whether interpretAsDst is enabled for the Qrono instance.
-     * @param yes - True to enable interpretAsDst, false to disable.
-     * @returns The Qrono instance.
+     * Sets the disambiguation option of the Qrono instance.
+     * @param value - The disambiguation option.
+     * @returns A new Qrono instance with the updated disambiguation.
      */
-    interpretAsDst(yes: boolean): Qrono
+    disambiguation(value: Disambiguation): Qrono
 
     /**
      * Returns whether the Qrono instance is valid.