@stacksjs/datetime 0.70.88 → 0.70.91

package/dist/format.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Format a date using token-based format strings.
+ *
+ * Supported tokens:
+ * - YYYY: 4-digit year
+ * - YY: 2-digit year
+ * - MMMM: Full month name (January)
+ * - MMM: Short month name (Jan)
+ * - MM: 2-digit month (01-12)
+ * - M: Month (1-12)
+ * - DD: 2-digit day (01-31)
+ * - D: Day (1-31)
+ * - dddd: Full weekday name (Wednesday)
+ * - ddd: Short weekday name (Wed)
+ * - d: Narrow weekday (W)
+ * - HH: 24-hour padded (00-23)
+ * - H: 24-hour (0-23)
+ * - hh: 12-hour padded (01-12)
+ * - h: 12-hour (1-12)
+ * - mm: Minutes padded (00-59)
+ * - m: Minutes (0-59)
+ * - ss: Seconds padded (00-59)
+ * - s: Seconds (0-59)
+ * - A: AM/PM
+ * - a: am/pm
+ * - Z: Timezone offset (+0800)
+ *
+ * @param inputDate - A Date object or ISO 8601 string
+ * @param formatStr - Token-based format string (default: 'YYYY-MM-DD')
+ * @param localeOrOptions - A locale string or options object with locale and tz (IANA timezone)
+ */
+export declare function format(inputDate: DateInput, formatStr?: string, localeOrOptions?: string | FormatOptions): string;
+declare interface FormatOptions {
+  locale?: string
+  tz?: string
+}
+declare type DateInput = Date | string;

package/dist/format.js

@@ -0,0 +1,100 @@
+function toDate(input) {
+  if (input instanceof Date)
+    return input;
+  const d = new Date(input);
+  if (Number.isNaN(d.getTime()))
+    throw Error(`Invalid date: ${input}`);
+  return d;
+}
+function pad(n, len = 2) {
+  return String(n).padStart(len, "0");
+}
+function getPartsInTz(date, tz, locale) {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: !1
+  }).formatToParts(date), get = (type) => parts.find((p) => p.type === type)?.value ?? "", year = Number.parseInt(get("year"), 10), month = Number.parseInt(get("month"), 10), day = Number.parseInt(get("day"), 10);
+  let hour = Number.parseInt(get("hour"), 10);
+  if (hour === 24)
+    hour = 0;
+  const minute = Number.parseInt(get("minute"), 10), second = Number.parseInt(get("second"), 10), weekday = new Intl.DateTimeFormat(locale, { timeZone: tz, weekday: "long" }).format(date), weekdayShort = new Intl.DateTimeFormat(locale, { timeZone: tz, weekday: "short" }).format(date), weekdayNarrow = new Intl.DateTimeFormat(locale, { timeZone: tz, weekday: "narrow" }).format(date), monthLong = new Intl.DateTimeFormat(locale, { timeZone: tz, month: "long" }).format(date), monthShort = new Intl.DateTimeFormat(locale, { timeZone: tz, month: "short" }).format(date), utcParts = new Intl.DateTimeFormat("en-US", {
+    timeZone: "UTC",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: !1
+  }).formatToParts(date), getUtc = (type) => utcParts.find((p) => p.type === type)?.value ?? "", utcDate = new Date(Date.UTC(Number.parseInt(getUtc("year"), 10), Number.parseInt(getUtc("month"), 10) - 1, Number.parseInt(getUtc("day"), 10), Number.parseInt(getUtc("hour"), 10) === 24 ? 0 : Number.parseInt(getUtc("hour"), 10), Number.parseInt(getUtc("minute"), 10), Number.parseInt(getUtc("second"), 10))), offsetMs = new Date(Date.UTC(year, month - 1, day, hour, minute, second)).getTime() - utcDate.getTime(), offsetMin = Math.round(offsetMs / 60000), sign = offsetMin >= 0 ? "+" : "-", absMin = Math.abs(offsetMin), tzOffset = `${sign}${pad(Math.floor(absMin / 60))}${pad(absMin % 60)}`;
+  return { year, month, day, hour, minute, second, weekday, weekdayShort, weekdayNarrow, monthLong, monthShort, tzOffset };
+}
+function buildTokens(p) {
+  const hours12 = p.hour % 12 || 12;
+  return {
+    YYYY: String(p.year),
+    YY: String(p.year).slice(-2),
+    MMMM: p.monthLong,
+    MMM: p.monthShort,
+    MM: pad(p.month),
+    M: String(p.month),
+    DD: pad(p.day),
+    D: String(p.day),
+    dddd: p.weekday,
+    ddd: p.weekdayShort,
+    d: p.weekdayNarrow,
+    HH: pad(p.hour),
+    H: String(p.hour),
+    hh: pad(hours12),
+    h: String(hours12),
+    mm: pad(p.minute),
+    m: String(p.minute),
+    ss: pad(p.second),
+    s: String(p.second),
+    A: p.hour < 12 ? "AM" : "PM",
+    a: p.hour < 12 ? "am" : "pm",
+    Z: p.tzOffset
+  };
+}
+const TOKEN_KEYS = ["YYYY", "MMMM", "dddd", "MMM", "ddd", "YY", "MM", "DD", "HH", "hh", "mm", "ss", "M", "D", "d", "H", "h", "m", "s", "A", "a", "Z"], TOKEN_PATTERN = new RegExp(TOKEN_KEYS.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"), "g");
+export function format(inputDate, formatStr = "YYYY-MM-DD", localeOrOptions = "en") {
+  const date = toDate(inputDate), opts = typeof localeOrOptions === "string" ? { locale: localeOrOptions } : localeOrOptions, locale = opts.locale ?? "en", tz = opts.tz;
+  if (tz) {
+    const parts = getPartsInTz(date, tz, locale), tokens = buildTokens(parts);
+    return formatStr.replace(TOKEN_PATTERN, (match) => tokens[match] ?? match);
+  }
+  const hours24 = date.getHours(), hours12 = hours24 % 12 || 12, tokens = {
+    YYYY: String(date.getFullYear()),
+    YY: String(date.getFullYear()).slice(-2),
+    MMMM: new Intl.DateTimeFormat(locale, { month: "long" }).format(date),
+    MMM: new Intl.DateTimeFormat(locale, { month: "short" }).format(date),
+    MM: pad(date.getMonth() + 1),
+    M: String(date.getMonth() + 1),
+    DD: pad(date.getDate()),
+    D: String(date.getDate()),
+    dddd: new Intl.DateTimeFormat(locale, { weekday: "long" }).format(date),
+    ddd: new Intl.DateTimeFormat(locale, { weekday: "short" }).format(date),
+    d: new Intl.DateTimeFormat(locale, { weekday: "narrow" }).format(date),
+    HH: pad(hours24),
+    H: String(hours24),
+    hh: pad(hours12),
+    h: String(hours12),
+    mm: pad(date.getMinutes()),
+    m: String(date.getMinutes()),
+    ss: pad(date.getSeconds()),
+    s: String(date.getSeconds()),
+    A: hours24 < 12 ? "AM" : "PM",
+    a: hours24 < 12 ? "am" : "pm",
+    Z: (() => {
+      const offset = -date.getTimezoneOffset(), sign = offset >= 0 ? "+" : "-", abs = Math.abs(offset);
+      return `${sign}${pad(Math.floor(abs / 60))}${pad(abs % 60)}`;
+    })()
+  };
+  return formatStr.replace(TOKEN_PATTERN, (match) => tokens[match] ?? match);
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+export { DateTime, now } from './now';
+export { format } from './format';
+export { parse } from './parse';
+/**
+ * Format a date using a token-based format string.
+ * This is a convenience alias for `format()`.
+ *
+ * @example
+ * ```ts
+ * dateFormat(new Date(), 'YYYY-MM-DD HH:mm:ss')
+ * dateFormat('2024-03-15', 'MMMM D, YYYY')
+ * ```
+ */
+export { format as dateFormat } from './format';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { DateTime, now } from "./now";
+export { format } from "./format";
+export { parse } from "./parse";
+export { format as dateFormat } from "./format";

package/dist/now.d.ts

@@ -0,0 +1,90 @@
+import { format } from './format';
+import { parse } from './parse';
+/**
+ * Get the current date/time as a DateTime instance.
+ * Inspired by Laravel's `now()` helper.
+ *
+ * @example
+ * ```ts
+ * now().toDateString()        // '2024-03-15'
+ * now().format('MMMM D, YYYY') // 'March 15, 2024'
+ * now().addDays(7).toDateString()
+ * now().startOfMonth().toDateString()
+ * now().diffInDays(someOtherDate)
+ * ```
+ */
+export declare function now(): DateTime;
+declare interface FormatOptions {
+  locale?: string
+  tz?: string
+}
+declare type DateInput = Date | string;
+/**
+ * A fluent DateTime wrapper inspired by Laravel's Carbon.
+ *
+ * Provides chainable date manipulation, formatting, and comparison
+ * with zero external dependencies.
+ */
+export declare class DateTime {
+  constructor(date?: DateInput, formatStr?: string);
+  static now(): DateTime;
+  static create(year: number, month?: number, day?: number, hour?: number, minute?: number, second?: number): DateTime;
+  static fromDate(date: Date): DateTime;
+  static parse(dateStr: string, formatStr?: string): DateTime;
+  format(formatStr: string, localeOrOptions?: string | FormatOptions): string;
+  toDateString(): string;
+  toTimeString(): string;
+  toDateTimeString(): string;
+  toISOString(): string;
+  toString(): string;
+  get year(): number;
+  get month(): number;
+  get day(): number;
+  get hour(): number;
+  get minute(): number;
+  get second(): number;
+  get dayOfWeek(): number;
+  get timestamp(): number;
+  setYear(year: number): DateTime;
+  setMonth(month: number): DateTime;
+  setDay(day: number): DateTime;
+  setHour(hour: number): DateTime;
+  setMinute(minute: number): DateTime;
+  setSecond(second: number): DateTime;
+  addSeconds(n: number): DateTime;
+  addMinutes(n: number): DateTime;
+  addHours(n: number): DateTime;
+  addDays(n: number): DateTime;
+  addWeeks(n: number): DateTime;
+  addMonths(n: number): DateTime;
+  addYears(n: number): DateTime;
+  subSeconds(n: number): DateTime;
+  subMinutes(n: number): DateTime;
+  subHours(n: number): DateTime;
+  subDays(n: number): DateTime;
+  subWeeks(n: number): DateTime;
+  subMonths(n: number): DateTime;
+  subYears(n: number): DateTime;
+  startOfDay(): DateTime;
+  endOfDay(): DateTime;
+  startOfMonth(): DateTime;
+  endOfMonth(): DateTime;
+  startOfYear(): DateTime;
+  endOfYear(): DateTime;
+  isBefore(other: DateTime | Date): boolean;
+  isAfter(other: DateTime | Date): boolean;
+  isSame(other: DateTime | Date): boolean;
+  isSameDay(other: DateTime | Date): boolean;
+  isBetween(start: DateTime | Date, end: DateTime | Date): boolean;
+  isPast(): boolean;
+  isFuture(): boolean;
+  isToday(): boolean;
+  isLeapYear(): boolean;
+  diffInSeconds(other: DateTime | Date): number;
+  diffInMinutes(other: DateTime | Date): number;
+  diffInHours(other: DateTime | Date): number;
+  diffInDays(other: DateTime | Date): number;
+  toNativeDate(): Date;
+  toJSON(): string;
+  valueOf(): number;
+}

package/dist/now.js

@@ -0,0 +1,231 @@
+import { format } from "./format";
+import { parse } from "./parse";
+
+export class DateTime {
+  date;
+  constructor(date, formatStr) {
+    if (!date)
+      this.date = new Date;
+    else if (date instanceof Date)
+      this.date = new Date(date.getTime());
+    else if (formatStr)
+      this.date = parse(date, formatStr);
+    else
+      this.date = parse(date);
+  }
+  static now() {
+    return new DateTime;
+  }
+  static create(year, month = 1, day = 1, hour = 0, minute = 0, second = 0) {
+    return new DateTime(new Date(year, month - 1, day, hour, minute, second));
+  }
+  static fromDate(date) {
+    return new DateTime(date);
+  }
+  static parse(dateStr, formatStr) {
+    return new DateTime(dateStr, formatStr);
+  }
+  format(formatStr, localeOrOptions) {
+    return format(this.date, formatStr, localeOrOptions);
+  }
+  toDateString() {
+    return format(this.date, "YYYY-MM-DD");
+  }
+  toTimeString() {
+    return format(this.date, "HH:mm:ss");
+  }
+  toDateTimeString() {
+    return format(this.date, "YYYY-MM-DD HH:mm:ss");
+  }
+  toISOString() {
+    return this.date.toISOString();
+  }
+  toString() {
+    return this.toDateTimeString();
+  }
+  get year() {
+    return this.date.getFullYear();
+  }
+  get month() {
+    return this.date.getMonth() + 1;
+  }
+  get day() {
+    return this.date.getDate();
+  }
+  get hour() {
+    return this.date.getHours();
+  }
+  get minute() {
+    return this.date.getMinutes();
+  }
+  get second() {
+    return this.date.getSeconds();
+  }
+  get dayOfWeek() {
+    return this.date.getDay();
+  }
+  get timestamp() {
+    return this.date.getTime();
+  }
+  setYear(year) {
+    const d = new Date(this.date);
+    d.setFullYear(year);
+    return new DateTime(d);
+  }
+  setMonth(month) {
+    const d = new Date(this.date);
+    d.setMonth(month - 1);
+    return new DateTime(d);
+  }
+  setDay(day) {
+    const d = new Date(this.date);
+    d.setDate(day);
+    return new DateTime(d);
+  }
+  setHour(hour) {
+    const d = new Date(this.date);
+    d.setHours(hour);
+    return new DateTime(d);
+  }
+  setMinute(minute) {
+    const d = new Date(this.date);
+    d.setMinutes(minute);
+    return new DateTime(d);
+  }
+  setSecond(second) {
+    const d = new Date(this.date);
+    d.setSeconds(second);
+    return new DateTime(d);
+  }
+  addSeconds(n) {
+    return new DateTime(new Date(this.date.getTime() + n * 1000));
+  }
+  addMinutes(n) {
+    return new DateTime(new Date(this.date.getTime() + n * 60000));
+  }
+  addHours(n) {
+    return new DateTime(new Date(this.date.getTime() + n * 3600000));
+  }
+  addDays(n) {
+    const d = new Date(this.date);
+    d.setDate(d.getDate() + n);
+    return new DateTime(d);
+  }
+  addWeeks(n) {
+    return this.addDays(n * 7);
+  }
+  addMonths(n) {
+    const d = new Date(this.date);
+    d.setMonth(d.getMonth() + n);
+    return new DateTime(d);
+  }
+  addYears(n) {
+    const d = new Date(this.date);
+    d.setFullYear(d.getFullYear() + n);
+    return new DateTime(d);
+  }
+  subSeconds(n) {
+    return this.addSeconds(-n);
+  }
+  subMinutes(n) {
+    return this.addMinutes(-n);
+  }
+  subHours(n) {
+    return this.addHours(-n);
+  }
+  subDays(n) {
+    return this.addDays(-n);
+  }
+  subWeeks(n) {
+    return this.addWeeks(-n);
+  }
+  subMonths(n) {
+    return this.addMonths(-n);
+  }
+  subYears(n) {
+    return this.addYears(-n);
+  }
+  startOfDay() {
+    const d = new Date(this.date);
+    d.setHours(0, 0, 0, 0);
+    return new DateTime(d);
+  }
+  endOfDay() {
+    const d = new Date(this.date);
+    d.setHours(23, 59, 59, 999);
+    return new DateTime(d);
+  }
+  startOfMonth() {
+    const d = new Date(this.date);
+    d.setDate(1);
+    d.setHours(0, 0, 0, 0);
+    return new DateTime(d);
+  }
+  endOfMonth() {
+    const d = new Date(this.date.getFullYear(), this.date.getMonth() + 1, 0, 23, 59, 59, 999);
+    return new DateTime(d);
+  }
+  startOfYear() {
+    return new DateTime(new Date(this.date.getFullYear(), 0, 1, 0, 0, 0, 0));
+  }
+  endOfYear() {
+    return new DateTime(new Date(this.date.getFullYear(), 11, 31, 23, 59, 59, 999));
+  }
+  isBefore(other) {
+    const otherTime = other instanceof DateTime ? other.timestamp : other.getTime();
+    return this.date.getTime() < otherTime;
+  }
+  isAfter(other) {
+    const otherTime = other instanceof DateTime ? other.timestamp : other.getTime();
+    return this.date.getTime() > otherTime;
+  }
+  isSame(other) {
+    const otherTime = other instanceof DateTime ? other.timestamp : other.getTime();
+    return this.date.getTime() === otherTime;
+  }
+  isSameDay(other) {
+    const o = other instanceof Date ? other : other.toNativeDate();
+    return this.date.getFullYear() === o.getFullYear() && this.date.getMonth() === o.getMonth() && this.date.getDate() === o.getDate();
+  }
+  isBetween(start, end) {
+    return this.isAfter(start) && this.isBefore(end);
+  }
+  isPast() {
+    return this.date.getTime() < Date.now();
+  }
+  isFuture() {
+    return this.date.getTime() > Date.now();
+  }
+  isToday() {
+    return this.isSameDay(new Date);
+  }
+  isLeapYear() {
+    const y = this.date.getFullYear();
+    return y % 4 === 0 && y % 100 !== 0 || y % 400 === 0;
+  }
+  diffInSeconds(other) {
+    const otherTime = other instanceof DateTime ? other.timestamp : other.getTime();
+    return Math.floor((this.date.getTime() - otherTime) / 1000);
+  }
+  diffInMinutes(other) {
+    return Math.floor(this.diffInSeconds(other) / 60);
+  }
+  diffInHours(other) {
+    return Math.floor(this.diffInSeconds(other) / 3600);
+  }
+  diffInDays(other) {
+    return Math.floor(this.diffInSeconds(other) / 86400);
+  }
+  toNativeDate() {
+    return new Date(this.date.getTime());
+  }
+  toJSON() {
+    return this.toISOString();
+  }
+  valueOf() {
+    return this.date.getTime();
+  }
+}
+export function now() {
+  return DateTime.now();
+}

package/dist/parse.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Parse a date string into a Date object.
+ *
+ * When a format string is provided, extracts date parts using the same tokens
+ * as the format function (YYYY, MM, DD, HH, mm, ss, etc.).
+ *
+ * If the format includes a Z token, the parsed offset is applied so the
+ * returned Date represents the correct instant in time.
+ *
+ * When no format is given, falls back to native Date parsing (with a fix
+ * for date-only ISO strings being treated as local time, not UTC).
+ */
+export declare function parse(dateStr: string, formatStr?: string, _locale?: string): Date;

package/dist/parse.js

@@ -0,0 +1,81 @@
+export function parse(dateStr, formatStr, _locale) {
+  if (!formatStr) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
+      const [y, m, d] = dateStr.split("-").map(Number);
+      if (y === void 0 || m === void 0 || d === void 0)
+        throw Error(`Unable to parse date: ${dateStr}`);
+      return new Date(y, m - 1, d);
+    }
+    const d = new Date(dateStr);
+    if (Number.isNaN(d.getTime()))
+      throw Error(`Unable to parse date: ${dateStr}`);
+    return d;
+  }
+  const tokenDefs = {
+    YYYY: { regex: "(\\d{4})", field: "year" },
+    YY: { regex: "(\\d{2})", field: "shortYear" },
+    MMMM: { regex: "(\\w+)", field: "monthName" },
+    MMM: { regex: "(\\w+)", field: "monthNameShort" },
+    MM: { regex: "(\\d{2})", field: "month" },
+    M: { regex: "(\\d{1,2})", field: "month" },
+    DD: { regex: "(\\d{2})", field: "day" },
+    D: { regex: "(\\d{1,2})", field: "day" },
+    HH: { regex: "(\\d{2})", field: "hours" },
+    H: { regex: "(\\d{1,2})", field: "hours" },
+    hh: { regex: "(\\d{2})", field: "hours12" },
+    h: { regex: "(\\d{1,2})", field: "hours12" },
+    mm: { regex: "(\\d{2})", field: "minutes" },
+    m: { regex: "(\\d{1,2})", field: "minutes" },
+    ss: { regex: "(\\d{2})", field: "seconds" },
+    s: { regex: "(\\d{1,2})", field: "seconds" },
+    A: { regex: "(AM|PM)", field: "ampm" },
+    a: { regex: "(am|pm)", field: "ampm" },
+    Z: { regex: "([+-]\\d{4})", field: "tz" }
+  }, sortedTokens = Object.keys(tokenDefs).sort((a, b) => b.length - a.length), tokenRegex = new RegExp(sortedTokens.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|"), "g"), fields = [], regexStr = formatStr.replace(tokenRegex, (match) => {
+    const def = tokenDefs[match];
+    if (def) {
+      fields.push(def.field);
+      return def.regex;
+    }
+    return match;
+  }), result = new RegExp(`^${regexStr}$`).exec(dateStr);
+  if (!result)
+    throw Error(`Unable to parse "${dateStr}" with format "${formatStr}"`);
+  const parts = {};
+  for (let i = 0;i < fields.length; i++) {
+    const field = fields[i], value = result[i + 1];
+    if (field !== void 0 && value !== void 0)
+      parts[field] = value;
+  }
+  let month = 0;
+  if (parts.month)
+    month = Number.parseInt(parts.month, 10) - 1;
+  else if (parts.monthName || parts.monthNameShort) {
+    const name = (parts.monthName || parts.monthNameShort || "").toLowerCase(), months = ["january", "february", "march", "april", "may", "june", "july", "august", "september", "october", "november", "december"], shortMonths = ["jan", "feb", "mar", "apr", "may", "jun", "jul", "aug", "sep", "oct", "nov", "dec"];
+    let idx = months.indexOf(name);
+    if (idx === -1)
+      idx = shortMonths.indexOf(name);
+    if (idx === -1)
+      throw Error(`Unknown month: ${parts.monthName || parts.monthNameShort}`);
+    month = idx;
+  }
+  let year = parts.year ? Number.parseInt(parts.year, 10) : new Date().getFullYear();
+  if (parts.shortYear) {
+    const shortYear = Number.parseInt(parts.shortYear, 10);
+    year = shortYear >= 70 ? 1900 + shortYear : 2000 + shortYear;
+  }
+  let hours = Number.parseInt(parts.hours || parts.hours12 || "0", 10);
+  if (parts.ampm) {
+    const isPM = parts.ampm.toLowerCase() === "pm";
+    if (isPM && hours < 12)
+      hours += 12;
+    if (!isPM && hours === 12)
+      hours = 0;
+  }
+  const day = Number.parseInt(parts.day || "1", 10), minutes = Number.parseInt(parts.minutes || "0", 10), seconds = Number.parseInt(parts.seconds || "0", 10);
+  if (parts.tz) {
+    const sign = parts.tz[0] === "+" ? 1 : -1, tzHours = Number.parseInt(parts.tz.slice(1, 3), 10), tzMinutes = Number.parseInt(parts.tz.slice(3, 5), 10), offsetMs = sign * (tzHours * 60 + tzMinutes) * 60000, utcMs = Date.UTC(year, month, day, hours, minutes, seconds) - offsetMs;
+    return new Date(utcMs);
+  }
+  return new Date(year, month, day, hours, minutes, seconds);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/datetime",
   "type": "module",
-  "version": "0.70.88",
+  "version": "0.70.91",
   "description": "The Stacks datetime helpers.",
   "author": "Chris Breuer",
   "contributors": [
@@ -54,7 +54,7 @@
   },
   "devDependencies": {
     "better-dx": "^0.2.16",
-    "@stacksjs/utils": "0.70.88"
+    "@stacksjs/utils": "0.70.91"
   },
   "sideEffects": false
 }