@timestamp-js/core 0.1.0-beta.0 → 0.1.0-rc.1

package/README.md

@@ -15,14 +15,14 @@ pnpm add @timestamp-js/core
 ## Basic Usage
 
 ```ts
-import { addToDate, addToDateClamped, getDateTime, parseTimestamp } from "@timestamp-js/core";
+import { addToDate, addToDateClamped, getDateTime, parseTimestamp } from '@timestamp-js/core'
 
-const start = parseTimestamp("2026-06-08T09:30:15.250Z");
-const end = start ? addToDate(start, { day: 2, minute: 45 }) : null;
-const billingDate = start ? addToDateClamped(start, { month: 1 }) : null;
+const start = parseTimestamp('2026-06-08T09:30:15.250Z')
+const end = start ? addToDate(start, { day: 2, minute: 45 }) : null
+const billingDate = start ? addToDateClamped(start, { month: 1 }) : null
 
-console.log(end ? getDateTime(end) : "Invalid date");
-console.log(billingDate ? getDateTime(billingDate) : "Invalid date");
+console.log(end ? getDateTime(end) : 'Invalid date')
+console.log(billingDate ? getDateTime(billingDate) : 'Invalid date')
 ```
 
 ## Timestamp Values
@@ -30,11 +30,11 @@ console.log(billingDate ? getDateTime(billingDate) : "Invalid date");
 Timestamp objects are immutable. Parsers and update helpers return frozen objects, and functions that change date/time fields return a new Timestamp instead of mutating the original.
 
 ```ts
-const start = parseTimestamp("2026-06-08 09:30")!;
-const next = addToDate(start, { day: 1 });
+const start = parseTimestamp('2026-06-08 09:30')!
+const next = addToDate(start, { day: 1 })
 
-console.log(start.date); // 2026-06-08
-console.log(next.date); // 2026-06-09
+console.log(start.date) // 2026-06-08
+console.log(next.date) // 2026-06-09
 ```
 
 ## Supported Input Shape
@@ -77,12 +77,13 @@ The publishable package lives in `packages/lib` so the repository follows the sa
 - Convert native `Date` objects into Timestamp objects.
 - Compare dates, times, date-times, and timestamp ranges, including optional second and millisecond precision.
 - Generate day and interval lists for calendar-style views.
+- Generate adapter-aware calendar timestamps and day lists for optional calendar packages.
 - Format weekday and month names through `Intl.DateTimeFormat`.
 - Keep the public surface small, typed, immutable, and runtime-agnostic while the package stabilizes.
 
 ## Future Scope
 
-The package is intentionally not trying to become a full general-purpose date library on day one. Planned evaluations include Temporal support, explicit timezone behavior, alternate calendar systems, duration helpers, Unix timestamp helpers, compact formatting masks, and a script-tag/browser build if CodePen-style demos need it.
+The package is intentionally not trying to become a full general-purpose date library on day one. Planned evaluations include Temporal support, explicit timezone behavior, more alternate calendar systems, compact formatting masks, and a script-tag/browser build if CodePen-style demos need it.
 
 ## Development
 

package/dist/calendar.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Stable identifier for a calendar implementation.
+ *
+ * The built-in Gregorian adapter uses `gregorian` as its package-facing id and
+ * `gregory` as its Intl calendar id.
+ */
+export type CalendarId = 'gregorian' | (string & {});
+/**
+ * Plain calendar date fields.
+ */
+export interface CalendarDateParts {
+    /**
+     * Calendar year.
+     */
+    readonly year: number;
+    /**
+     * Calendar month number. The first month is `1`.
+     */
+    readonly month: number;
+    /**
+     * Day of the month. The first day is `1`.
+     */
+    readonly day: number;
+}
+/**
+ * Calendar implementation contract used by Timestamp helpers.
+ *
+ * Calendar packages should implement this interface without import-time side
+ * effects. Core range and comparison helpers can use `epochDay` as a stable
+ * serial value instead of comparing calendar-specific year/month/day fields.
+ */
+export interface CalendarSystem {
+    /**
+     * Package-facing calendar id.
+     */
+    readonly id: CalendarId;
+    /**
+     * Optional Intl calendar id, when one exists.
+     */
+    readonly intlCalendar?: string;
+    /**
+     * Human-readable calendar name.
+     */
+    readonly label: string;
+    /**
+     * Number of months in a calendar year.
+     */
+    monthsInYear(year: number): number;
+    /**
+     * True when the calendar year has a leap day or leap month.
+     */
+    isLeapYear(year: number): boolean;
+    /**
+     * Number of days in the specified calendar month.
+     */
+    daysInMonth(year: number, month: number): number;
+    /**
+     * Converts a calendar date into a stable serial day.
+     *
+     * For Gregorian this is the number of UTC days since 1970-01-01. Other
+     * calendar adapters should return the serial day for the equivalent civil
+     * instant so comparisons and ranges can stay calendar-agnostic.
+     */
+    toEpochDay(date: CalendarDateParts): number;
+    /**
+     * Converts a stable serial day into calendar date fields.
+     */
+    fromEpochDay(epochDay: number): CalendarDateParts;
+    /**
+     * Moves a calendar date by a whole number of days.
+     */
+    addDays(date: CalendarDateParts, amount: number): CalendarDateParts;
+    /**
+     * Returns the next calendar date.
+     */
+    nextDay(date: CalendarDateParts): CalendarDateParts;
+    /**
+     * Returns the previous calendar date.
+     */
+    prevDay(date: CalendarDateParts): CalendarDateParts;
+    /**
+     * Returns day-of-year for a calendar date.
+     */
+    getDayOfYear(date: CalendarDateParts): number;
+    /**
+     * Returns weekday where Sunday is `0` and Saturday is `6`.
+     */
+    getWeekday(date: CalendarDateParts): number;
+}
+/**
+ * Formats calendar fields using the Timestamp package's fixed date format.
+ */
+export declare function formatCalendarDate(date: CalendarDateParts): string;
+/**
+ * Built-in proleptic Gregorian calendar adapter.
+ *
+ * This preserves the current Timestamp behavior and gives future calendar
+ * packages a concrete contract to implement.
+ */
+export declare const gregorianCalendar: CalendarSystem;
+//# sourceMappingURL=calendar.d.ts.map

package/dist/calendar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../src/calendar.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAA;AAEpD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB;;OAEG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAA;IAEvB;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAE9B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IAEtB;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAA;IAElC;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAEjC;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAA;IAEhD;;;;;;OAMG;IACH,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAAA;IAE3C;;OAEG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAAA;IAEjD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAAA;IAEnE;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,CAAA;IAEnD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,iBAAiB,GAAG,iBAAiB,CAAA;IAEnD;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAAA;IAE7C;;OAEG;IACH,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAAA;CAC5C;AAWD;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAElE;AAcD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,cA+C9B,CAAA"}

package/dist/calendar.js

@@ -0,0 +1,69 @@
+const MILLISECONDS_IN_DAY = 86400000;
+const GREGORIAN_DAYS_IN_MONTH = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+const GREGORIAN_DAYS_IN_MONTH_LEAP = [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+function padNumber(value, length) {
+    let padded = String(value);
+    while (padded.length < length) {
+        padded = '0' + padded;
+    }
+    return padded;
+}
+/**
+ * Formats calendar fields using the Timestamp package's fixed date format.
+ */
+export function formatCalendarDate(date) {
+    return `${padNumber(date.year, 4)}-${padNumber(date.month, 2)}-${padNumber(date.day, 2)}`;
+}
+function fromUtcDate(date) {
+    return {
+        year: date.getUTCFullYear(),
+        month: date.getUTCMonth() + 1,
+        day: date.getUTCDate(),
+    };
+}
+function toGregorianUtcDate(date) {
+    return new Date(Date.UTC(date.year, date.month - 1, date.day));
+}
+/**
+ * Built-in proleptic Gregorian calendar adapter.
+ *
+ * This preserves the current Timestamp behavior and gives future calendar
+ * packages a concrete contract to implement.
+ */
+export const gregorianCalendar = Object.freeze({
+    id: 'gregorian',
+    intlCalendar: 'gregory',
+    label: 'Gregorian',
+    monthsInYear() {
+        return 12;
+    },
+    isLeapYear(year) {
+        return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    },
+    daysInMonth(year, month) {
+        return (this.isLeapYear(year) ? GREGORIAN_DAYS_IN_MONTH_LEAP[month] : GREGORIAN_DAYS_IN_MONTH[month]);
+    },
+    toEpochDay(date) {
+        return Math.floor(Date.UTC(date.year, date.month - 1, date.day) / MILLISECONDS_IN_DAY);
+    },
+    fromEpochDay(epochDay) {
+        return fromUtcDate(new Date(epochDay * MILLISECONDS_IN_DAY));
+    },
+    addDays(date, amount) {
+        return this.fromEpochDay(this.toEpochDay(date) + amount);
+    },
+    nextDay(date) {
+        return this.addDays(date, 1);
+    },
+    prevDay(date) {
+        return this.addDays(date, -1);
+    },
+    getDayOfYear(date) {
+        const yearStart = this.toEpochDay({ year: date.year, month: 1, day: 1 });
+        return this.toEpochDay(date) - yearStart + 1;
+    },
+    getWeekday(date) {
+        return toGregorianUtcDate(date).getUTCDay();
+    },
+});
+//# sourceMappingURL=calendar.js.map

package/dist/calendar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.js","sourceRoot":"","sources":["../src/calendar.ts"],"names":[],"mappings":"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"}