foldkit 0.59.0 → 0.61.0

package/dist/calendar/arithmetic.d.ts

@@ -0,0 +1,140 @@
+import { type CalendarDate } from './calendarDate';
+/**
+ * Adds `n` days to a calendar date. Negative `n` subtracts days.
+ * Handles month and year rollovers correctly in both directions.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * Calendar.addDays(Calendar.make(2026, 4, 13), 5)
+ * // { year: 2026, month: 4, day: 18 }
+ *
+ * pipe(Calendar.make(2026, 4, 30), Calendar.addDays(1))
+ * // { year: 2026, month: 5, day: 1 }
+ * ```
+ */
+export declare const addDays: {
+    (n: number): (self: CalendarDate) => CalendarDate;
+    (self: CalendarDate, n: number): CalendarDate;
+};
+/**
+ * Subtracts `n` days from a calendar date. Equivalent to `addDays(self, -n)`.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * Calendar.subtractDays(Calendar.make(2026, 5, 1), 1)
+ * // { year: 2026, month: 4, day: 30 }
+ *
+ * pipe(Calendar.make(2026, 1, 1), Calendar.subtractDays(1))
+ * // { year: 2025, month: 12, day: 31 }
+ * ```
+ */
+export declare const subtractDays: {
+    (n: number): (self: CalendarDate) => CalendarDate;
+    (self: CalendarDate, n: number): CalendarDate;
+};
+/**
+ * Adds `n` months to a calendar date. Negative `n` subtracts months.
+ *
+ * Clamps the day to the last valid day of the resulting month when the
+ * original day would exceed it. So `addMonths(make(2026, 1, 31), 1)` returns
+ * February 28, 2026 (not March 3).
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * Calendar.addMonths(Calendar.make(2026, 4, 13), 3)
+ * // { year: 2026, month: 7, day: 13 }
+ *
+ * pipe(Calendar.make(2026, 1, 31), Calendar.addMonths(1))
+ * // { year: 2026, month: 2, day: 28 } — clamped from 31
+ * ```
+ */
+export declare const addMonths: {
+    (n: number): (self: CalendarDate) => CalendarDate;
+    (self: CalendarDate, n: number): CalendarDate;
+};
+/**
+ * Subtracts `n` months from a calendar date. Equivalent to `addMonths(self, -n)`.
+ */
+export declare const subtractMonths: {
+    (n: number): (self: CalendarDate) => CalendarDate;
+    (self: CalendarDate, n: number): CalendarDate;
+};
+/**
+ * Adds `n` years to a calendar date. Handles leap-year edge cases by clamping
+ * day-of-month when the target year's month is shorter (February 29 in a
+ * leap year + 1 year = February 28).
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * Calendar.addYears(Calendar.make(2024, 2, 29), 1)
+ * // { year: 2025, month: 2, day: 28 } — clamped
+ *
+ * pipe(Calendar.make(2026, 4, 13), Calendar.addYears(5))
+ * // { year: 2031, month: 4, day: 13 }
+ * ```
+ */
+export declare const addYears: {
+    (n: number): (self: CalendarDate) => CalendarDate;
+    (self: CalendarDate, n: number): CalendarDate;
+};
+/**
+ * Subtracts `n` years from a calendar date. Equivalent to `addYears(self, -n)`.
+ */
+export declare const subtractYears: {
+    (n: number): (self: CalendarDate) => CalendarDate;
+    (self: CalendarDate, n: number): CalendarDate;
+};
+/**
+ * Returns the number of days from `self` until `end`, positive when `end` is
+ * after `self`, negative when before, zero when equal. Matches `Temporal.PlainDate.until`.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * const today = Calendar.make(2026, 4, 13)
+ * const birthday = Calendar.make(2026, 7, 15)
+ *
+ * Calendar.daysUntil(today, birthday) // 93
+ * pipe(today, Calendar.daysUntil(birthday)) // 93
+ * ```
+ */
+export declare const daysUntil: {
+    (end: CalendarDate): (self: CalendarDate) => number;
+    (self: CalendarDate, end: CalendarDate): number;
+};
+/**
+ * Returns the number of days from `start` until `self`, positive when `self`
+ * is after `start`, negative when before, zero when equal. Matches
+ * `Temporal.PlainDate.since`.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * const today = Calendar.make(2026, 4, 13)
+ * const startOfYear = Calendar.make(2026, 1, 1)
+ *
+ * Calendar.daysSince(today, startOfYear) // 102
+ * pipe(today, Calendar.daysSince(startOfYear)) // 102
+ * ```
+ */
+export declare const daysSince: {
+    (start: CalendarDate): (self: CalendarDate) => number;
+    (self: CalendarDate, start: CalendarDate): number;
+};
+//# sourceMappingURL=arithmetic.d.ts.map

package/dist/calendar/arithmetic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arithmetic.d.ts","sourceRoot":"","sources":["../../src/calendar/arithmetic.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,YAAY,EAA2B,MAAM,gBAAgB,CAAA;AAyD3E;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,OAAO,EAAE;IACpB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAA;IACjD,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;CAK9C,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,EAAE;IACzB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAA;IACjD,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;CAI9C,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAA;IACjD,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;CAU7C,CAAA;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE;IAC3B,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAA;IACjD,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;CAI9C,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,QAAQ,EAAE;IACrB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAA;IACjD,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;CAK9C,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE;IAC1B,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,EAAE,YAAY,KAAK,YAAY,CAAA;IACjD,CAAC,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;CAI9C,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,GAAG,EAAE,YAAY,GAAG,CAAC,IAAI,EAAE,YAAY,KAAK,MAAM,CAAA;IACnD,CAAC,IAAI,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,GAAG,MAAM,CAAA;CAKhD,CAAA;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,EAAE;IACtB,CAAC,KAAK,EAAE,YAAY,GAAG,CAAC,IAAI,EAAE,YAAY,KAAK,MAAM,CAAA;IACrD,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,MAAM,CAAA;CAKlD,CAAA"}

package/dist/calendar/arithmetic.js

@@ -0,0 +1,169 @@
+import { Function } from 'effect';
+import { daysInMonth, unsafeMake } from './calendarDate';
+// NOTE: Rata Die conversion uses Howard Hinnant's algorithm, which correctly
+// handles all Gregorian dates including century and quadricentennial leap-year
+// boundaries. Treat `toRataDie`/`fromRataDie` as mathematical primitives —
+// their correctness is verified by the test suite, not by reading the formulas.
+// See http://howardhinnant.github.io/date_algorithms.html
+const MONTHS_PER_YEAR = 12;
+const DAYS_PER_YEAR = 365;
+// NOTE: Gregorian era constants for Howard Hinnant's Rata Die algorithm.
+// `YEARS_PER_ERA` is the length of the full Gregorian leap-year cycle.
+// `DAYS_PER_ERA` is the exact day count over that cycle (400 × 365.2425).
+// `EPOCH_DAY_OFFSET` aligns the Rata Die ordinal with 1970-01-01 = 0.
+const YEARS_PER_ERA = 400;
+const DAYS_PER_ERA = 146097;
+const EPOCH_DAY_OFFSET = 719468;
+const toRataDie = (date) => {
+    const { year, month, day } = date;
+    const adjustedYear = month <= 2 ? year - 1 : year;
+    const era = Math.floor(adjustedYear / YEARS_PER_ERA);
+    const yearOfEra = adjustedYear - era * YEARS_PER_ERA;
+    const dayOfYear = Math.floor((153 * (month > 2 ? month - 3 : month + 9) + 2) / 5) + day - 1;
+    const dayOfEra = yearOfEra * DAYS_PER_YEAR +
+        Math.floor(yearOfEra / 4) -
+        Math.floor(yearOfEra / 100) +
+        dayOfYear;
+    return era * DAYS_PER_ERA + dayOfEra - EPOCH_DAY_OFFSET;
+};
+const fromRataDie = (rataDie) => {
+    const shifted = rataDie + EPOCH_DAY_OFFSET;
+    const era = Math.floor(shifted / DAYS_PER_ERA);
+    const dayOfEra = shifted - era * DAYS_PER_ERA;
+    const yearOfEra = Math.floor((dayOfEra -
+        Math.floor(dayOfEra / 1460) +
+        Math.floor(dayOfEra / 36524) -
+        Math.floor(dayOfEra / 146096)) /
+        DAYS_PER_YEAR);
+    const year = yearOfEra + era * YEARS_PER_ERA;
+    const dayOfYear = dayOfEra -
+        (DAYS_PER_YEAR * yearOfEra +
+            Math.floor(yearOfEra / 4) -
+            Math.floor(yearOfEra / 100));
+    const monthAdjusted = Math.floor((5 * dayOfYear + 2) / 153);
+    const month = monthAdjusted < 10 ? monthAdjusted + 3 : monthAdjusted - 9;
+    const day = dayOfYear - Math.floor((153 * monthAdjusted + 2) / 5) + 1;
+    return unsafeMake(month <= 2 ? year + 1 : year, month, day);
+};
+/**
+ * Adds `n` days to a calendar date. Negative `n` subtracts days.
+ * Handles month and year rollovers correctly in both directions.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * Calendar.addDays(Calendar.make(2026, 4, 13), 5)
+ * // { year: 2026, month: 4, day: 18 }
+ *
+ * pipe(Calendar.make(2026, 4, 30), Calendar.addDays(1))
+ * // { year: 2026, month: 5, day: 1 }
+ * ```
+ */
+export const addDays = Function.dual(2, (self, n) => n === 0 ? self : fromRataDie(toRataDie(self) + n));
+/**
+ * Subtracts `n` days from a calendar date. Equivalent to `addDays(self, -n)`.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * Calendar.subtractDays(Calendar.make(2026, 5, 1), 1)
+ * // { year: 2026, month: 4, day: 30 }
+ *
+ * pipe(Calendar.make(2026, 1, 1), Calendar.subtractDays(1))
+ * // { year: 2025, month: 12, day: 31 }
+ * ```
+ */
+export const subtractDays = Function.dual(2, (self, n) => addDays(self, -n));
+/**
+ * Adds `n` months to a calendar date. Negative `n` subtracts months.
+ *
+ * Clamps the day to the last valid day of the resulting month when the
+ * original day would exceed it. So `addMonths(make(2026, 1, 31), 1)` returns
+ * February 28, 2026 (not March 3).
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * Calendar.addMonths(Calendar.make(2026, 4, 13), 3)
+ * // { year: 2026, month: 7, day: 13 }
+ *
+ * pipe(Calendar.make(2026, 1, 31), Calendar.addMonths(1))
+ * // { year: 2026, month: 2, day: 28 } — clamped from 31
+ * ```
+ */
+export const addMonths = Function.dual(2, (self, n) => {
+    const totalMonthsFromZero = self.year * MONTHS_PER_YEAR + (self.month - 1) + n;
+    const newYear = Math.floor(totalMonthsFromZero / MONTHS_PER_YEAR);
+    const newMonth = (((totalMonthsFromZero % MONTHS_PER_YEAR) + MONTHS_PER_YEAR) %
+        MONTHS_PER_YEAR) +
+        1;
+    const newDay = Math.min(self.day, daysInMonth(newYear, newMonth));
+    return unsafeMake(newYear, newMonth, newDay);
+});
+/**
+ * Subtracts `n` months from a calendar date. Equivalent to `addMonths(self, -n)`.
+ */
+export const subtractMonths = Function.dual(2, (self, n) => addMonths(self, -n));
+/**
+ * Adds `n` years to a calendar date. Handles leap-year edge cases by clamping
+ * day-of-month when the target year's month is shorter (February 29 in a
+ * leap year + 1 year = February 28).
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * Calendar.addYears(Calendar.make(2024, 2, 29), 1)
+ * // { year: 2025, month: 2, day: 28 } — clamped
+ *
+ * pipe(Calendar.make(2026, 4, 13), Calendar.addYears(5))
+ * // { year: 2031, month: 4, day: 13 }
+ * ```
+ */
+export const addYears = Function.dual(2, (self, n) => addMonths(self, n * MONTHS_PER_YEAR));
+/**
+ * Subtracts `n` years from a calendar date. Equivalent to `addYears(self, -n)`.
+ */
+export const subtractYears = Function.dual(2, (self, n) => addYears(self, -n));
+/**
+ * Returns the number of days from `self` until `end`, positive when `end` is
+ * after `self`, negative when before, zero when equal. Matches `Temporal.PlainDate.until`.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * const today = Calendar.make(2026, 4, 13)
+ * const birthday = Calendar.make(2026, 7, 15)
+ *
+ * Calendar.daysUntil(today, birthday) // 93
+ * pipe(today, Calendar.daysUntil(birthday)) // 93
+ * ```
+ */
+export const daysUntil = Function.dual(2, (self, end) => toRataDie(end) - toRataDie(self));
+/**
+ * Returns the number of days from `start` until `self`, positive when `self`
+ * is after `start`, negative when before, zero when equal. Matches
+ * `Temporal.PlainDate.since`.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { pipe } from 'effect'
+ *
+ * const today = Calendar.make(2026, 4, 13)
+ * const startOfYear = Calendar.make(2026, 1, 1)
+ *
+ * Calendar.daysSince(today, startOfYear) // 102
+ * pipe(today, Calendar.daysSince(startOfYear)) // 102
+ * ```
+ */
+export const daysSince = Function.dual(2, (self, start) => toRataDie(self) - toRataDie(start));

package/dist/calendar/calendarDate.d.ts

@@ -0,0 +1,162 @@
+import { Schema as S } from 'effect';
+/**
+ * Determines if a year is a leap year in the Gregorian calendar.
+ *
+ * A year is a leap year if it is divisible by 4, except for century years
+ * (divisible by 100) which must also be divisible by 400. So 2000 is a leap
+ * year but 1900 is not.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * Calendar.isLeapYear(2024) // true
+ * Calendar.isLeapYear(2026) // false
+ * Calendar.isLeapYear(2000) // true (divisible by 400)
+ * Calendar.isLeapYear(1900) // false (century, not divisible by 400)
+ * ```
+ */
+export declare const isLeapYear: (year: number) => boolean;
+/**
+ * Returns the number of days in a given month of a given year.
+ * Leap-year-aware: February returns 29 in leap years, 28 otherwise.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * Calendar.daysInMonth(2026, 1) // 31 (January)
+ * Calendar.daysInMonth(2026, 2) // 28 (February, non-leap)
+ * Calendar.daysInMonth(2024, 2) // 29 (February, leap)
+ * Calendar.daysInMonth(2026, 4) // 30 (April)
+ * ```
+ */
+export declare const daysInMonth: (year: number, month: number) => number;
+/**
+ * A calendar date — year, month, day. No time, no timezone.
+ *
+ * Models the same concept as Java's `LocalDate` or TC39's `Temporal.PlainDate`.
+ * Useful when you need to represent a date without a clock attached —
+ * birthdays, deadlines, form date inputs, event calendars.
+ *
+ * Validation ensures the date is a real calendar date: months are 1-12 and
+ * days are within the month's actual length. Leap-year-aware, so February 30
+ * is rejected and February 29 is only accepted in leap years.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { Schema as S } from 'effect'
+ *
+ * const date = Calendar.make(2026, 4, 13)
+ * S.decodeUnknownSync(Calendar.CalendarDate)({ year: 2026, month: 4, day: 13 })
+ * ```
+ */
+export declare const CalendarDate: S.filter<S.Struct<{
+    year: typeof S.Int;
+    month: S.filter<typeof S.Int>;
+    day: S.filter<typeof S.Int>;
+}>>;
+export type CalendarDate = typeof CalendarDate.Type;
+/**
+ * Type guard for `CalendarDate`. Returns true when `value` is a valid
+ * calendar date struct.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * Calendar.isCalendarDate({ year: 2026, month: 4, day: 13 }) // true
+ * Calendar.isCalendarDate({ year: 2026, month: 2, day: 30 }) // false
+ * Calendar.isCalendarDate('2026-04-13') // false
+ * ```
+ */
+export declare const isCalendarDate: (value: unknown) => value is CalendarDate;
+/**
+ * Constructs a `CalendarDate`, validating via Schema.
+ * Throws a `ParseError` if the combination is not a real calendar date
+ * (e.g. February 30, month 13, day 0).
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * const birthday = Calendar.make(1990, 7, 15)
+ * Calendar.make(2024, 2, 29) // OK, 2024 is a leap year
+ * Calendar.make(2026, 2, 29) // throws — not a leap year
+ * ```
+ */
+export declare const make: (year: number, month: number, day: number) => CalendarDate;
+/**
+ * Constructs a `CalendarDate` without Schema validation. Only for inputs the
+ * caller knows are valid — typically arithmetic results inside the calendar
+ * module. Consumers should prefer `make`.
+ */
+export declare const unsafeMake: (year: number, month: number, day: number) => CalendarDate;
+/**
+ * Constructs a `CalendarDate` from a JavaScript `Date` object, reading the
+ * year/month/day in the browser's local timezone.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * const date = Calendar.fromDateLocal(new Date())
+ * ```
+ */
+export declare const fromDateLocal: (date: Date) => CalendarDate;
+/**
+ * Constructs a `CalendarDate` from a JavaScript `Date` object, reading the
+ * year/month/day in a specific IANA timezone (e.g. `"America/New_York"`).
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * const bookingDate = Calendar.fromDateInZone(new Date(), 'America/New_York')
+ * ```
+ */
+export declare const fromDateInZone: (date: Date, timeZone: string) => CalendarDate;
+/**
+ * Converts a `CalendarDate` to a JavaScript `Date` object representing
+ * midnight at the start of that day in the browser's local timezone.
+ *
+ * Note: `Date` objects always carry a time and timezone component. This
+ * function intentionally pins the time to local midnight. For cross-timezone
+ * use, pass the result through an `Intl.DateTimeFormat` with an explicit
+ * timezone, or keep working with `CalendarDate`.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * const jsDate = Calendar.toDateLocal(Calendar.make(2026, 4, 13))
+ * ```
+ */
+export declare const toDateLocal: (calendarDate: CalendarDate) => Date;
+/**
+ * Schema transform between an ISO 8601 date string (`YYYY-MM-DD`) and a
+ * `CalendarDate`. Useful for form inputs, JSON serialization, URL query
+ * parameters, and hidden form input values.
+ *
+ * Decoding accepts only zero-padded ISO dates. Invalid calendar dates like
+ * `2026-02-30` decode the string shape but fail the `CalendarDate` filter.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { Schema as S } from 'effect'
+ *
+ * const decode = S.decodeUnknownSync(Calendar.CalendarDateFromIsoString)
+ * const encode = S.encodeSync(Calendar.CalendarDateFromIsoString)
+ *
+ * decode('2026-04-13') // { year: 2026, month: 4, day: 13 }
+ * encode(Calendar.make(2026, 4, 13)) // "2026-04-13"
+ * ```
+ */
+export declare const CalendarDateFromIsoString: S.transformOrFail<typeof S.String, S.filter<S.Struct<{
+    year: typeof S.Int;
+    month: S.filter<typeof S.Int>;
+    day: S.filter<typeof S.Int>;
+}>>, never>;
+//# sourceMappingURL=calendarDate.d.ts.map

package/dist/calendar/calendarDate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"calendarDate.d.ts","sourceRoot":"","sources":["../../src/calendar/calendarDate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,MAAM,IAAI,CAAC,EAAE,MAAM,QAAQ,CAAA;AAEjD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,OACgB,CAAA;AAE1D;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,KAAG,MAQzD,CAAA;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,YAAY;;;;GAUxB,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,IAAI,CAAA;AAEnD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,cAAc,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,YACtC,CAAA;AAEpB;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,IAAI,GAAI,MAAM,MAAM,EAAE,OAAO,MAAM,EAAE,KAAK,MAAM,KAAG,YACP,CAAA;AAEzD;;;;GAIG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,OAAO,MAAM,EACb,KAAK,MAAM,KACV,YACmE,CAAA;AAEtE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,IAAI,KAAG,YAC0B,CAAA;AAErE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,IAAI,EAAE,UAAU,MAAM,KAAG,YAa7D,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,GAAI,cAAc,YAAY,KAAG,IACc,CAAA;AAIvE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,yBAAyB;;;;WA4BrC,CAAA"}

package/dist/calendar/calendarDate.js

@@ -0,0 +1,196 @@
+import { ParseResult, Schema as S } from 'effect';
+/**
+ * Determines if a year is a leap year in the Gregorian calendar.
+ *
+ * A year is a leap year if it is divisible by 4, except for century years
+ * (divisible by 100) which must also be divisible by 400. So 2000 is a leap
+ * year but 1900 is not.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * Calendar.isLeapYear(2024) // true
+ * Calendar.isLeapYear(2026) // false
+ * Calendar.isLeapYear(2000) // true (divisible by 400)
+ * Calendar.isLeapYear(1900) // false (century, not divisible by 400)
+ * ```
+ */
+export const isLeapYear = (year) => year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+/**
+ * Returns the number of days in a given month of a given year.
+ * Leap-year-aware: February returns 29 in leap years, 28 otherwise.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * Calendar.daysInMonth(2026, 1) // 31 (January)
+ * Calendar.daysInMonth(2026, 2) // 28 (February, non-leap)
+ * Calendar.daysInMonth(2024, 2) // 29 (February, leap)
+ * Calendar.daysInMonth(2026, 4) // 30 (April)
+ * ```
+ */
+export const daysInMonth = (year, month) => {
+    if (month === 2) {
+        return isLeapYear(year) ? 29 : 28;
+    }
+    if (month === 4 || month === 6 || month === 9 || month === 11) {
+        return 30;
+    }
+    return 31;
+};
+/**
+ * A calendar date — year, month, day. No time, no timezone.
+ *
+ * Models the same concept as Java's `LocalDate` or TC39's `Temporal.PlainDate`.
+ * Useful when you need to represent a date without a clock attached —
+ * birthdays, deadlines, form date inputs, event calendars.
+ *
+ * Validation ensures the date is a real calendar date: months are 1-12 and
+ * days are within the month's actual length. Leap-year-aware, so February 30
+ * is rejected and February 29 is only accepted in leap years.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { Schema as S } from 'effect'
+ *
+ * const date = Calendar.make(2026, 4, 13)
+ * S.decodeUnknownSync(Calendar.CalendarDate)({ year: 2026, month: 4, day: 13 })
+ * ```
+ */
+export const CalendarDate = S.Struct({
+    year: S.Int,
+    month: S.Int.pipe(S.between(1, 12)),
+    day: S.Int.pipe(S.between(1, 31)),
+}).pipe(S.filter(({ year, month, day }) => day <= daysInMonth(year, month), {
+    identifier: 'CalendarDate',
+    description: 'a valid calendar date (year, month 1-12, day within month length)',
+}));
+/**
+ * Type guard for `CalendarDate`. Returns true when `value` is a valid
+ * calendar date struct.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * Calendar.isCalendarDate({ year: 2026, month: 4, day: 13 }) // true
+ * Calendar.isCalendarDate({ year: 2026, month: 2, day: 30 }) // false
+ * Calendar.isCalendarDate('2026-04-13') // false
+ * ```
+ */
+export const isCalendarDate = S.is(CalendarDate);
+/**
+ * Constructs a `CalendarDate`, validating via Schema.
+ * Throws a `ParseError` if the combination is not a real calendar date
+ * (e.g. February 30, month 13, day 0).
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * const birthday = Calendar.make(1990, 7, 15)
+ * Calendar.make(2024, 2, 29) // OK, 2024 is a leap year
+ * Calendar.make(2026, 2, 29) // throws — not a leap year
+ * ```
+ */
+export const make = (year, month, day) => S.decodeUnknownSync(CalendarDate)({ year, month, day });
+/**
+ * Constructs a `CalendarDate` without Schema validation. Only for inputs the
+ * caller knows are valid — typically arithmetic results inside the calendar
+ * module. Consumers should prefer `make`.
+ */
+export const unsafeMake = (year, month, day) => CalendarDate.make({ year, month, day }, { disableValidation: true });
+/**
+ * Constructs a `CalendarDate` from a JavaScript `Date` object, reading the
+ * year/month/day in the browser's local timezone.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * const date = Calendar.fromDateLocal(new Date())
+ * ```
+ */
+export const fromDateLocal = (date) => unsafeMake(date.getFullYear(), date.getMonth() + 1, date.getDate());
+/**
+ * Constructs a `CalendarDate` from a JavaScript `Date` object, reading the
+ * year/month/day in a specific IANA timezone (e.g. `"America/New_York"`).
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * const bookingDate = Calendar.fromDateInZone(new Date(), 'America/New_York')
+ * ```
+ */
+export const fromDateInZone = (date, timeZone) => {
+    const formatter = new Intl.DateTimeFormat('en-US', {
+        timeZone,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    });
+    const parts = formatter.formatToParts(date);
+    const getPart = (type) => {
+        const part = parts.find(candidate => candidate.type === type);
+        return part ? Number(part.value) : 0;
+    };
+    return unsafeMake(getPart('year'), getPart('month'), getPart('day'));
+};
+/**
+ * Converts a `CalendarDate` to a JavaScript `Date` object representing
+ * midnight at the start of that day in the browser's local timezone.
+ *
+ * Note: `Date` objects always carry a time and timezone component. This
+ * function intentionally pins the time to local midnight. For cross-timezone
+ * use, pass the result through an `Intl.DateTimeFormat` with an explicit
+ * timezone, or keep working with `CalendarDate`.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ *
+ * const jsDate = Calendar.toDateLocal(Calendar.make(2026, 4, 13))
+ * ```
+ */
+export const toDateLocal = (calendarDate) => new Date(calendarDate.year, calendarDate.month - 1, calendarDate.day);
+const isoPattern = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * Schema transform between an ISO 8601 date string (`YYYY-MM-DD`) and a
+ * `CalendarDate`. Useful for form inputs, JSON serialization, URL query
+ * parameters, and hidden form input values.
+ *
+ * Decoding accepts only zero-padded ISO dates. Invalid calendar dates like
+ * `2026-02-30` decode the string shape but fail the `CalendarDate` filter.
+ *
+ * @example
+ * ```ts
+ * import { Calendar } from 'foldkit'
+ * import { Schema as S } from 'effect'
+ *
+ * const decode = S.decodeUnknownSync(Calendar.CalendarDateFromIsoString)
+ * const encode = S.encodeSync(Calendar.CalendarDateFromIsoString)
+ *
+ * decode('2026-04-13') // { year: 2026, month: 4, day: 13 }
+ * encode(Calendar.make(2026, 4, 13)) // "2026-04-13"
+ * ```
+ */
+export const CalendarDateFromIsoString = S.transformOrFail(S.String, CalendarDate, {
+    strict: true,
+    decode: (input, _options, ast) => {
+        const match = input.match(isoPattern);
+        if (match === null) {
+            return ParseResult.fail(new ParseResult.Type(ast, input, `Expected ISO date (YYYY-MM-DD), got ${JSON.stringify(input)}`));
+        }
+        const [, yearString, monthString, dayString] = match;
+        return ParseResult.succeed({
+            year: Number(yearString),
+            month: Number(monthString),
+            day: Number(dayString),
+        });
+    },
+    encode: ({ year, month, day }) => ParseResult.succeed(`${String(year).padStart(4, '0')}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`),
+});