native-dates 0.0.0-stage → 0.0.6

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2025 Jack Lukic
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,42 @@
-# Temporary Holding Version
+# <img alt="" src=".github/logo.svg" height="47" align="absmiddle"> Native Dates
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> A thin date library built on the browser's Temporal and Intl APIs
+
+- Four nouns for what code actually means: `DateTime`, `CalendarDate`, `Time` and `Duration`
+- Time zones, daylight transitions and calendar math handled by the platform
+- Frozen values that lead in the console with their human-readable `text`
+- Natural phrases (`'1h 30m'`, `today().plus(2, 'days').at('9am')`) and `Intl` presets
+- Plugins you import only if you use them
+- About 6 KB brotli, with zero dependencies
+
+Native Dates leaves calendar math and formatting to the platform. The browser's [Temporal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) and [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) APIs know every time zone, daylight transition and locale, and this library speaks them in plain English: four nouns instead of nine, one word per thought, and values that cannot be mutated in place.
+
+```js
+import { date, duration, now, today } from 'native-dates';
+import '@native-dates/plugins/ranges';
+import '@native-dates/plugins/tokens';
+
+const standup = today().next('monday').at('9:30am', 'America/Los_Angeles');
+standup.in('Europe/Berlin').format('dddd, MMM D [at] HH:mm z');
+
+const sprint = date('2026-09-01').to(2, 'weeks');
+sprint.contains(today());
+sprint.points('day');
+
+const remaining = now().until(standup);
+remaining.total('hours');
+duration('1h 30m').plus(15, 'minutes').format('short');
+```
+
+## Packages
+
+| Package | Description |
+| --- | --- |
+| [native-dates](src) | The four nouns (`DateTime`, `CalendarDate`, `Time`, `Duration`), presets, comparisons and `configure()` |
+| [@native-dates/plugins](packages/plugins) | The plugins (`ranges`, `tokens`, `relative`, `zones`, `loose`, `legacy-date`), each installed by importing it |
+| [@native-dates/polyfill](packages/polyfill) | Loads `temporal-polyfill` only when `globalThis.Temporal` is absent |
+| [@native-dates/core](packages/core) | Native Dates under its scoped name, a thin re-export |
+
+## License
+
+[ISC](LICENSE)

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "native-dates",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.6",
+  "title": "Native Dates",
+  "description": "Temporal, spoken plainly. Datetimes, dates, times, durations and ranges on the browser's Temporal and Intl APIs",
+  "author": "Jack Lukic",
+  "license": "ISC",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./helpers/*": "./src/helpers/*.js"
+  },
+  "files": [
+    "src",
+    "types",
+    "README.md",
+    "LICENSE"
+  ],
+  "workspaces": [
+    ".",
+    "packages/*"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "size": "node tools/size.js",
+    "format": "npx dprint fmt",
+    "setup": "npx simple-git-hooks"
+  },
+  "devDependencies": {
+    "dprint": "^0.50.0",
+    "esbuild": "^0.25.0",
+    "simple-git-hooks": "^2.11.1"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "bash tools/hooks/pre-commit",
+    "commit-msg": "bash tools/hooks/commit-msg \"$1\""
+  }
+}

package/src/calendar-date.js

@@ -0,0 +1,393 @@
+import { DateTime } from './date-time.js';
+import { anchored } from './duration.js';
+import { guard, loosely, parseLoose, refuse, refuseType, requireLoose } from './helpers/errors.js';
+import { fieldsFrom, temporalDurationOf } from './helpers/fields.js';
+import { formatIntl, intlOptions, unknownFormat } from './helpers/format.js';
+import { IS_CALENDAR_DATE } from './helpers/identity.js';
+import { isDate, isDevelopment, isNumber, isPlainObject, isString } from './helpers/types.js';
+import {
+  inspect,
+  isDigits,
+  isPlainDate,
+  isPlainDateTime,
+  isZonedDateTime,
+  plural,
+  quarterStart,
+  singularKeys,
+  stepOf,
+  timeUnits,
+  unit,
+  weekdayNumber,
+  wholeNumbers,
+  withParts,
+} from './helpers/units.js';
+import { weekStart, zoneId } from './helpers/zones.js';
+import { Time } from './time.js';
+
+/*
+  a calendar date with no time and no zone: a due date, a birthday, a booking night. it is not a
+  moment, so it never shifts when read from another zone
+*/
+
+const hasTime = /[T ]\d{1,2}(?::?\d{2})?/;
+const hasOffset = /(?:[zZ]|[+-]\d{2}(?::?\d{2})?)$/;
+
+export class CalendarDate {
+  // brand calendar date
+  get [IS_CALENDAR_DATE]() {
+    return true;
+  }
+  static [Symbol.hasInstance](value) {
+    return !!value?.[IS_CALENDAR_DATE];
+  }
+
+  #plain;
+
+  // date(2026, 9, 6), date(input, zone), or date(input, { zone, loose })
+  constructor(input, monthOrOptions, day) {
+    if (isDigits(input) && (isNumber(monthOrOptions) || isDigits(monthOrOptions))) {
+      [input, monthOrOptions, day] = [Number(input), Number(monthOrOptions), day === undefined ? day : Number(day)];
+    }
+    const settings = isPlainObject(monthOrOptions)
+      ? monthOrOptions
+      : isString(monthOrOptions)
+      ? { zone: monthOrOptions }
+      : {};
+    this.#plain =
+      isPlainDate(input) && settings.zone === undefined && !settings.loose && settings.dayFirst === undefined
+        ? input
+        : CalendarDate.#read(input, isNumber(monthOrOptions) ? monthOrOptions : undefined, day, settings);
+    // the parts are own properties, so a value prints them in a console without a click, in the order a
+    // preview reads: the text first, filled once the parts it reads are in, then month, day, year
+    this.text = undefined;
+    const plain = this.#plain;
+    this.month = plain.month;
+    this.day = plain.day;
+    this.year = plain.year;
+    this.weekday = plain.dayOfWeek;
+    this.text = this.format();
+    Object.freeze(this);
+  }
+
+  static #read(input, month, day, settings) {
+    if (settings.zone !== undefined) {
+      zoneId(settings.zone);
+    }
+    if (settings.loose || settings.dayFirst !== undefined) {
+      requireLoose(settings.loose ? 'loose' : 'dayFirst');
+    }
+    if (input === undefined || input === null) {
+      return refuseType('notADate', String(input), {
+        explanation: isDevelopment
+          ? 'today() is the current day. a missing value is refused so an absent field never silently becomes today'
+          : 0,
+      });
+    }
+    if (isNumber(input) && isNumber(month)) {
+      return guard(
+        () => {
+          if (!wholeNumbers([input, month, day])) {
+            throw new RangeError('a date reads whole numbers');
+          }
+          return Temporal.PlainDate.from({ year: input, month, day: day ?? 1 }, { overflow: 'reject' });
+        },
+        'unreadableDate',
+        `${input}-${month}-${day}`,
+      );
+    }
+    if (input instanceof CalendarDate) {
+      return input.toTemporal();
+    }
+    if (input instanceof DateTime) {
+      return input.toTemporal().toPlainDate();
+    }
+    if (isNumber(input)) {
+      return refuseType('notADate', String(input), {
+        explanation: isDevelopment
+          ? 'a number alone is ambiguous. epoch milliseconds are a datetime, datetime(n).date, and a year needs its month and day, date(2026, 9, 6)'
+          : 0,
+      });
+    }
+    if (isDate(input)) {
+      return new DateTime(input, settings).toTemporal().toPlainDate();
+    }
+    if (isString(input)) {
+      try {
+        return CalendarDate.#parse(input);
+      }
+      catch (error) {
+        if (!settings.loose || (error.code !== 'notADate' && error.code !== 'unreadableDate')) {
+          throw error;
+        }
+        const zoned = parseLoose(input, settings.zone, settings.dayFirst);
+        if (!zoned) {
+          throw error;
+        }
+        return zoned.toPlainDate();
+      }
+    }
+    if (isZonedDateTime(input) || isPlainDateTime(input)) {
+      return input.toPlainDate();
+    }
+    if (isPlainObject(input)) {
+      return guard(
+        () => Temporal.PlainDate.from(singularKeys(input), { overflow: 'reject' }),
+        'unreadableDate',
+        JSON.stringify(input),
+      );
+    }
+    return refuseType('notADate', String(input), {
+      explanation: isDevelopment
+        ? "a date is an ISO string like '2026-09-06', three numbers, a fields object, a datetime, or a Temporal value"
+        : 0,
+    });
+  }
+
+  // a wall-clock string keeps its day and drops the clock. a string carrying Z or an offset is an
+  // instant, and which day it falls on depends on the zone, so it is refused with the two ways to choose
+  static #parse(text) {
+    const trimmed = text.trim();
+    if (hasTime.test(trimmed) && hasOffset.test(trimmed)) {
+      refuseType('notADate', text, {
+        explanation: isDevelopment
+          ? 'that string is an instant. datetime(text, zone).date chooses its day in a zone, and so does { loose: true, zone } with plugins/loose'
+          : 0,
+      });
+    }
+    return guard(
+      () => Temporal.PlainDate.from(trimmed),
+      'unreadableDate',
+      text,
+      isDevelopment ? "write ISO 8601: '2026-09-06'. plugins/loose adds { loose: true } for what Date reads" : 0,
+    );
+  }
+
+  /*******************************
+              Reads
+  *******************************/
+
+  get quarter() {
+    return Math.ceil(this.#plain.month / 3);
+  }
+  get dayOfYear() {
+    return this.#plain.dayOfYear;
+  }
+  get weekOfYear() {
+    return this.#plain.weekOfYear;
+  }
+  get daysInMonth() {
+    return this.#plain.daysInMonth;
+  }
+  get daysInYear() {
+    return this.#plain.daysInYear;
+  }
+  isLeapYear() {
+    return this.#plain.inLeapYear;
+  }
+  isWeekend() {
+    return this.#plain.dayOfWeek >= 6;
+  }
+  isWeekday() {
+    return this.#plain.dayOfWeek < 6;
+  }
+
+  /*******************************
+            Arithmetic
+  *******************************/
+
+  plus(amount, name) {
+    return new CalendarDate(
+      guard(() => this.#plain.add(CalendarDate.#dateFields(amount, name)), 'cannotAdd', `${amount} ${name ?? ''}`),
+    );
+  }
+
+  minus(amount, name) {
+    return new CalendarDate(
+      guard(
+        () => this.#plain.subtract(CalendarDate.#dateFields(amount, name)),
+        'cannotSubtract',
+        `${amount} ${name ?? ''}`,
+      ),
+    );
+  }
+
+  static #dateFields(amount, name) {
+    const fields = fieldsFrom(amount, name);
+    const clock = timeUnits.find((time) => fields[plural(time)]);
+    if (clock) {
+      refuse('notADateUnit', `${clock}s`, {
+        explanation: isDevelopment
+          ? 'a date has no clock. add days, or combine it with a time first: date.at(time, zone).plus(hours)'
+          : 0,
+      });
+    }
+    return temporalDurationOf(fields);
+  }
+
+  set(fields, value) {
+    const changes = isString(fields) ? { [unit(fields)]: value } : singularKeys(fields);
+    return new CalendarDate(
+      guard(() => withParts(this.#plain, changes), 'cannotSet', JSON.stringify(changes)),
+    );
+  }
+
+  // a week starts on the configured first day, or on the one given: a picker's first day is a prop
+  startOf(name, firstDay) {
+    switch (unit(name)) {
+      case 'year':
+        return new CalendarDate(this.#plain.with({ month: 1, day: 1 }));
+      case 'quarter':
+        return new CalendarDate(this.#plain.with({ month: quarterStart(this.month), day: 1 }));
+      case 'month':
+        return new CalendarDate(this.#plain.with({ day: 1 }));
+      case 'week':
+        return new CalendarDate(this.#plain.subtract({ days: (this.weekday - weekStart(firstDay) + 7) % 7 }));
+      case 'day':
+        return this;
+      default:
+        return refuse('notADateUnit', String(name), {
+          explanation: isDevelopment ? 'a date starts at year, quarter, month, week or day' : 0,
+        });
+    }
+  }
+
+  endOf(name, firstDay) {
+    return this.startOf(name, firstDay).plus(stepOf(unit(name))).minus({ days: 1 });
+  }
+
+  next(weekday) {
+    const delta = (weekdayNumber(weekday) - this.weekday + 7) % 7 || 7;
+    return this.plus({ days: delta });
+  }
+
+  previous(weekday) {
+    const delta = (this.weekday - weekdayNumber(weekday) + 7) % 7 || 7;
+    return this.minus({ days: delta });
+  }
+
+  /*******************************
+            Comparison
+  *******************************/
+
+  equals(other) {
+    return this.#compare(other) === 0;
+  }
+
+  #compare(other) {
+    return Temporal.PlainDate.compare(this.#plain, new CalendarDate(other).toTemporal());
+  }
+
+  isBefore(other) {
+    return this.#compare(other) < 0;
+  }
+
+  isAfter(other) {
+    return this.#compare(other) > 0;
+  }
+
+  isSame(other, name, firstDay) {
+    if (name === undefined) {
+      return this.equals(other);
+    }
+    return this.startOf(name, firstDay).equals(new CalendarDate(other).startOf(name, firstDay));
+  }
+
+  isPast(zone) {
+    return this.isBefore(today(zone));
+  }
+
+  isFuture(zone) {
+    return this.isAfter(today(zone));
+  }
+
+  isToday(zone) {
+    return this.equals(today(zone));
+  }
+
+  isTomorrow(zone) {
+    return this.equals(today(zone).plus({ days: 1 }));
+  }
+
+  isYesterday(zone) {
+    return this.equals(today(zone).minus({ days: 1 }));
+  }
+
+  /*******************************
+             Measure
+  *******************************/
+
+  until(other, name) {
+    const end = new CalendarDate(other);
+    const span = anchored(this.#plain.until(end.toTemporal(), { largestUnit: 'year' }), this.#plain);
+    return name === undefined ? span : span.total(name);
+  }
+
+  since(other, name) {
+    return new CalendarDate(other).until(this, name);
+  }
+
+  at(when, zone) {
+    const plainTime = new Time(when ?? '00:00').toTemporal();
+    return new DateTime(this.#plain.toZonedDateTime({ timeZone: zoneId(zone), plainTime }));
+  }
+
+  /*******************************
+              Output
+  *******************************/
+
+  format(spec, locale) {
+    const options = intlOptions('date', spec);
+    return options ? formatIntl('date', this.#plain, options, locale) : unknownFormat(spec);
+  }
+
+  toString() {
+    return this.#plain.toString();
+  }
+
+  toJSON() {
+    return this.#plain.toString();
+  }
+
+  toJSDate(zone) {
+    return this.at('00:00', zone).toJSDate();
+  }
+
+  toTemporal() {
+    return this.#plain;
+  }
+
+  valueOf() {
+    return refuse('notANumber', String(this), {
+      explanation: isDevelopment
+        ? 'a date is not a point on the number line. compare with isBefore, isAfter or equals, or measure with until'
+        : 0,
+    });
+  }
+
+  // + gives the string, while < and - still refuse through valueOf
+  [Symbol.toPrimitive](hint) {
+    return hint === 'number' ? this.valueOf() : this.toString();
+  }
+
+  [inspect]() {
+    return `CalendarDate(${this.#plain})`;
+  }
+}
+
+CalendarDate.prototype.add = CalendarDate.prototype.plus;
+CalendarDate.prototype.subtract = CalendarDate.prototype.minus;
+CalendarDate.prototype.remove = CalendarDate.prototype.minus;
+
+export const date = (input, monthOrOptions, day) => {
+  const build = () =>
+    input instanceof CalendarDate && monthOrOptions === undefined
+      ? input
+      : new CalendarDate(input, monthOrOptions, day);
+  return isPlainObject(monthOrOptions) && monthOrOptions.loose ? loosely(build) : build();
+};
+
+export const today = (zone) => new CalendarDate(Temporal.Now.plainDateISO(zoneId(zone)));
+export const tomorrow = (zone) => today(zone).plus({ days: 1 });
+export const yesterday = (zone) => today(zone).minus({ days: 1 });
+
+export const isCalendarDate = (value) => value instanceof CalendarDate;