Published foldkit API declarations for calendar.
./calendar
@wsagency/wseffect-foldkit · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES
This entry point is published in @wsagency/wseffect-foldkit@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.
import * as Wseffect from '@wsagency/wseffect-foldkit/calendar'
Exported declarations
addDays
Adds `n` days to a calendar date. Negative `n` subtracts days.
Handles month and year rollovers correctly in both directions.
addDays: {
(n: number): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, n: number): CalendarDate;
}
addMonths
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).
addMonths: {
(n: number): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, n: number): CalendarDate;
}
addYears
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).
addYears: {
(n: number): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, n: number): CalendarDate;
}
between
Returns `true` when `self` is within the inclusive range `[minimum, maximum]`.
between: {
(options: {
readonly minimum: CalendarDate;
readonly maximum: CalendarDate;
}): (self: CalendarDate) => boolean;
(self: CalendarDate, options: {
readonly minimum: CalendarDate;
readonly maximum: CalendarDate;
}): boolean;
}
CalendarDate
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.
CalendarDate: Schema.Struct<{
readonly year: Schema.Int;
readonly month: Schema.Int;
readonly day: Schema.Int;
}>
CalendarDate
export type CalendarDate = typeof CalendarDate.Type;
CalendarDateFromIsoString
Schema codec 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.
CalendarDateFromIsoString: Schema.decodeTo<Schema.Struct<{
readonly year: Schema.Int;
readonly month: Schema.Int;
readonly day: Schema.Int;
}>, Schema.String, never, never>
clamp
Clamps `self` to the inclusive range `[minimum, maximum]`. Returns
`minimum` when `self` is before it, `maximum` when `self` is after it,
and `self` itself otherwise.
clamp: {
(options: {
readonly minimum: CalendarDate;
readonly maximum: CalendarDate;
}): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, options: {
readonly minimum: CalendarDate;
readonly maximum: CalendarDate;
}): CalendarDate;
}
DateFormat
A non-empty ordered list of parts rendered left to right. Because ordering
lives in the data rather than in the formatting functions, a locale whose
dates read day-first or year-first renders correctly without a code change.
DateFormat: Schema.NonEmptyArray<import("../schema/index.js").TaggedUnion<{
readonly MonthName: {};
readonly ShortMonthName: {};
readonly MonthNumber: {};
readonly PaddedMonthNumber: {};
readonly DayNumber: {};
readonly PaddedDayNumber: {};
readonly DayName: {};
readonly ShortDayName: {};
readonly YearNumber: {};
readonly LiteralText: {
text: Schema.String;
};
}>>
DateFormat
export type DateFormat = typeof DateFormat.Type;
DatePart
One part of a `DateFormat`. Name parts draw from the `LocaleConfig`, number
parts draw from the date, and `LiteralText` supplies separators,
punctuation, or suffixes such as `年`.
`MonthName`, `DayName`, and their `Short*` counterparts select from the
corresponding locale name arrays. `MonthNumber` and `DayNumber` render
unpadded numbers; their `Padded*` counterparts render two digits.
`YearNumber` renders the full year.
DatePart: import("../schema/index.js").TaggedUnion<{
readonly MonthName: {};
readonly ShortMonthName: {};
readonly MonthNumber: {};
readonly PaddedMonthNumber: {};
readonly DayNumber: {};
readonly PaddedDayNumber: {};
readonly DayName: {};
readonly ShortDayName: {};
readonly YearNumber: {};
readonly LiteralText: {
text: Schema.String;
};
}>
DatePart
export type DatePart = typeof DatePart.Type;
dayOfWeek
Returns the day of the week for a calendar date.
dayOfWeek: (self: CalendarDate) => DayOfWeek
DayOfWeek
Schema for days of the week, Sunday through Saturday. Tagged union preferred
over 0-6 numeric indices to avoid magic numbers at call sites.
DayOfWeek: Schema.Literals<readonly ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]>
DayOfWeek
export type DayOfWeek = typeof DayOfWeek.Type;
daysInMonth
Returns the number of days in a given month of a given year.
Leap-year-aware: February returns 29 in leap years, 28 otherwise.
daysInMonth: (year: number, month: number) => number
daysSince
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`.
daysSince: {
(start: CalendarDate): (self: CalendarDate) => number;
(self: CalendarDate, start: CalendarDate): number;
}
daysUntil
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`.
daysUntil: {
(end: CalendarDate): (self: CalendarDate) => number;
(self: CalendarDate, end: CalendarDate): number;
}
defaultEnglishLocale
Default English (United States) locale. Calendar components default to this
when initialization receives no locale. Consumers who want a different
locale pass their own `LocaleConfig`.
defaultEnglishLocale: LocaleConfig
endOfWeek
Returns the end-of-week date — six days after the start of the week.
endOfWeek: {
(firstDayOfWeek: DayOfWeek): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, firstDayOfWeek: DayOfWeek): CalendarDate;
}
Equivalence
Value-based equivalence for calendar dates.
Equivalence: Equivalence_.Equivalence<CalendarDate>
firstOfMonth
Returns the first day of the month containing `self`.
firstOfMonth: (self: CalendarDate) => CalendarDate
format
Renders a calendar date through an arbitrary `DateFormat`. The four named
formatters below are this function applied to the matching field of the
`LocaleConfig`; reach for it directly when a view needs a shape the locale
does not carry.
format: {
(locale: LocaleConfig, dateFormat: DateFormat): (self: CalendarDate) => string;
(self: CalendarDate, locale: LocaleConfig, dateFormat: DateFormat): string;
}
formatAriaLabel
Renders a calendar date through the locale's `ariaLabelFormat`, suitable
for `aria-label` on a grid cell. Under `defaultEnglishLocale`:
`"Thursday, January 15, 2026"`.
formatAriaLabel: {
(locale: LocaleConfig): (self: CalendarDate) => string;
(self: CalendarDate, locale: LocaleConfig): string;
}
formatLong
Renders a calendar date through the locale's `longFormat`. Under
`defaultEnglishLocale`: `"January 15, 2026"`.
formatLong: {
(locale: LocaleConfig): (self: CalendarDate) => string;
(self: CalendarDate, locale: LocaleConfig): string;
}
formatMonthYear
Renders the month and year of a calendar date through the locale's
`monthYearFormat`, for calendar headings and month-cell labels. Under
`defaultEnglishLocale`: `"January 2026"`.
The day of `self` is ignored, so callers with only a year and month can pass
any valid day.
formatMonthYear: {
(locale: LocaleConfig): (self: CalendarDate) => string;
(self: CalendarDate, locale: LocaleConfig): string;
}
formatShort
Renders a calendar date through the locale's `shortFormat`. Under
`defaultEnglishLocale`: `"Jan 15, 2026"`.
formatShort: {
(locale: LocaleConfig): (self: CalendarDate) => string;
(self: CalendarDate, locale: LocaleConfig): string;
}
fromDateInZone
Constructs a `CalendarDate` from a JavaScript `Date` object, reading the
year/month/day in a specific IANA timezone (e.g. `"America/New_York"`).
fromDateInZone: (date: Date, timeZone: string) => CalendarDate
fromDateLocal
Constructs a `CalendarDate` from a JavaScript `Date` object, reading the
year/month/day in the browser's local timezone.
fromDateLocal: (date: Date) => CalendarDate
isAfter
Returns `true` when `self` is strictly after `that`.
isAfter: {
(that: CalendarDate): (self: CalendarDate) => boolean;
(self: CalendarDate, that: CalendarDate): boolean;
}
isAfterOrEqual
Returns `true` when `self` is after or equal to `that`.
isAfterOrEqual: {
(that: CalendarDate): (self: CalendarDate) => boolean;
(self: CalendarDate, that: CalendarDate): boolean;
}
isBefore
Returns `true` when `self` is strictly before `that`.
isBefore: {
(that: CalendarDate): (self: CalendarDate) => boolean;
(self: CalendarDate, that: CalendarDate): boolean;
}
isBeforeOrEqual
Returns `true` when `self` is before or equal to `that`.
isBeforeOrEqual: {
(that: CalendarDate): (self: CalendarDate) => boolean;
(self: CalendarDate, that: CalendarDate): boolean;
}
isCalendarDate
Type guard for `CalendarDate`. Returns true when `value` is a valid
calendar date struct.
isCalendarDate: (value: unknown) => value is CalendarDate
isEqual
Returns `true` when two calendar dates represent the same day.
isEqual: {
(that: CalendarDate): (self: CalendarDate) => boolean;
(self: CalendarDate, that: CalendarDate): boolean;
}
isLeapYear
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.
isLeapYear: (year: number) => boolean
lastOfMonth
Returns the last day of the month containing `self`. Leap-year aware
for February.
lastOfMonth: (self: CalendarDate) => CalendarDate
LocaleConfig
export type LocaleConfig = typeof LocaleConfig.Type;
LocaleConfig
Locale configuration for rendering calendar dates. Contains only data: the
month and day names, the first day of the week, and the `DateFormat` for
each of the four shapes the formatters produce. Formatting functions
(`formatLong`, `formatShort`, `formatAriaLabel`, `formatMonthYear`) are
separate exports that take a `LocaleConfig` as input.
Day names are always stored Sunday-first in the config; `firstDayOfWeek`
controls how the view rotates them at render time.
LocaleConfig: Schema.Struct<{
readonly firstDayOfWeek: Schema.Literals<readonly ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]>;
readonly monthNames: Schema.Tuple<readonly [Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String]>;
readonly shortMonthNames: Schema.Tuple<readonly [Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String]>;
readonly dayNames: Schema.Tuple<readonly [Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String]>;
readonly shortDayNames: Schema.Tuple<readonly [Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String, Schema.String]>;
readonly longFormat: Schema.NonEmptyArray<import("../schema/index.js").TaggedUnion<{
readonly MonthName: {};
readonly ShortMonthName: {};
readonly MonthNumber: {};
readonly PaddedMonthNumber: {};
readonly DayNumber: {};
readonly PaddedDayNumber: {};
readonly DayName: {};
readonly ShortDayName: {};
readonly YearNumber: {};
readonly LiteralText: {
text: Schema.String;
};
}>>;
readonly shortFormat: Schema.NonEmptyArray<import("../schema/index.js").TaggedUnion<{
readonly MonthName: {};
readonly ShortMonthName: {};
readonly MonthNumber: {};
readonly PaddedMonthNumber: {};
readonly DayNumber: {};
readonly PaddedDayNumber: {};
readonly DayName: {};
readonly ShortDayName: {};
readonly YearNumber: {};
readonly LiteralText: {
text: Schema.String;
};
}>>;
readonly ariaLabelFormat: Schema.NonEmptyArray<import("../schema/index.js").TaggedUnion<{
readonly MonthName: {};
readonly ShortMonthName: {};
readonly MonthNumber: {};
readonly PaddedMonthNumber: {};
readonly DayNumber: {};
readonly PaddedDayNumber: {};
readonly DayName: {};
readonly ShortDayName: {};
readonly YearNumber: {};
readonly LiteralText: {
text: Schema.String;
};
}>>;
readonly monthYearFormat: Schema.NonEmptyArray<Schema.Union<readonly [Schema.TaggedStruct<"MonthName", {}> & ((value?: void | {
readonly _tag?: "MonthName";
} | undefined) => {
readonly _tag: "MonthName";
}), Schema.TaggedStruct<"ShortMonthName", {}> & ((value?: void | {
readonly _tag?: "ShortMonthName";
} | undefined) => {
readonly _tag: "ShortMonthName";
}), Schema.TaggedStruct<"MonthNumber", {}> & ((value?: void | {
readonly _tag?: "MonthNumber";
} | undefined) => {
readonly _tag: "MonthNumber";
}), Schema.TaggedStruct<"PaddedMonthNumber", {}> & ((value?: void | {
readonly _tag?: "PaddedMonthNumber";
} | undefined) => {
readonly _tag: "PaddedMonthNumber";
}), Schema.TaggedStruct<"YearNumber", {}> & ((value?: void | {
readonly _tag?: "YearNumber";
} | undefined) => {
readonly _tag: "YearNumber";
}), Schema.TaggedStruct<"LiteralText", {
readonly text: Schema.String;
}> & ((value: {
readonly _tag?: "LiteralText";
readonly text: string;
}) => {
readonly _tag: "LiteralText";
readonly text: string;
})]>>;
}>
make
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).
make: (year: number, month: number, day: number) => CalendarDate
max
Returns the later of two calendar dates.
max: {
(that: CalendarDate): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, that: CalendarDate): CalendarDate;
}
min
Returns the earlier of two calendar dates.
min: {
(that: CalendarDate): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, that: CalendarDate): CalendarDate;
}
MonthYearFormat
export type MonthYearFormat = typeof MonthYearFormat.Type;
MonthYearFormat
A non-empty format restricted to month and year parts.
MonthYearFormat: Schema.NonEmptyArray<Schema.Union<readonly [Schema.TaggedStruct<"MonthName", {}> & ((value?: void | {
readonly _tag?: "MonthName";
} | undefined) => {
readonly _tag: "MonthName";
}), Schema.TaggedStruct<"ShortMonthName", {}> & ((value?: void | {
readonly _tag?: "ShortMonthName";
} | undefined) => {
readonly _tag: "ShortMonthName";
}), Schema.TaggedStruct<"MonthNumber", {}> & ((value?: void | {
readonly _tag?: "MonthNumber";
} | undefined) => {
readonly _tag: "MonthNumber";
}), Schema.TaggedStruct<"PaddedMonthNumber", {}> & ((value?: void | {
readonly _tag?: "PaddedMonthNumber";
} | undefined) => {
readonly _tag: "PaddedMonthNumber";
}), Schema.TaggedStruct<"YearNumber", {}> & ((value?: void | {
readonly _tag?: "YearNumber";
} | undefined) => {
readonly _tag: "YearNumber";
}), Schema.TaggedStruct<"LiteralText", {
readonly text: Schema.String;
}> & ((value: {
readonly _tag?: "LiteralText";
readonly text: string;
}) => {
readonly _tag: "LiteralText";
readonly text: string;
})]>>
Order
Total ordering over calendar dates. Uses lexicographic comparison on
`year`, then `month`, then `day` — which matches calendar chronology
because the struct fields are already in the right order.
Order: EffectOrder.Order<CalendarDate>
startOfWeek
Returns the start-of-week date for the week containing `self`, where
`firstDayOfWeek` specifies which day begins the week. Returns `self`
itself when it already falls on `firstDayOfWeek`.
startOfWeek: {
(firstDayOfWeek: DayOfWeek): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, firstDayOfWeek: DayOfWeek): CalendarDate;
}
subtractDays
Subtracts `n` days from a calendar date. Equivalent to `addDays(self, -n)`.
subtractDays: {
(n: number): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, n: number): CalendarDate;
}
subtractMonths
Subtracts `n` months from a calendar date. Equivalent to `addMonths(self, -n)`.
subtractMonths: {
(n: number): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, n: number): CalendarDate;
}
subtractYears
Subtracts `n` years from a calendar date. Equivalent to `addYears(self, -n)`.
subtractYears: {
(n: number): (self: CalendarDate) => CalendarDate;
(self: CalendarDate, n: number): CalendarDate;
}
toDateLocal
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`.
toDateLocal: (calendarDate: CalendarDate) => Date
today
Effect-based accessors for the current calendar date. Uses Effect's `Clock`
service under the hood, so tests can freeze time with `TestClock` and
production uses the real system clock.
This is the **only** impurity boundary in the calendar module — every
other function in this module is referentially transparent.
today: {
/**
* The current calendar date in the browser's local timezone.
*/
local: Effect.Effect<{
readonly year: number;
readonly month: number;
readonly day: number;
}, never, never>;
/**
* The current calendar date in a specific IANA timezone
* (e.g. `"America/New_York"`, `"Europe/London"`, `"Asia/Tokyo"`).
*/
inZone: (timeZone: string) => Effect.Effect<{
readonly year: number;
readonly month: number;
readonly day: number;
}, never, never>;
}