Documentation navigation

Published API · 0.1.0-rc.1

foldkit · calendar

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>;
}