@dyadav0607/calendardate 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dharamvir Kumar Yadav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,107 @@
+# @dyadav0607/calendardate
+
+Calendar dates without a timezone — a year, a month, a day, and the arithmetic
+that goes with them.
+
+```ts
+import { parseCalendarDate, addMonths, formatIso } from '@dyadav0607/calendardate'
+
+const released = parseCalendarDate('2026-08-19')
+formatIso(addMonths(released, -6)) // '2026-02-19'
+```
+
+No dependencies. Under 200 lines.
+
+```sh
+npm install @dyadav0607/calendardate
+```
+
+## Why
+
+A birthday is not an instant. Neither is a release date, a due date, or a public
+holiday. "The 19th of August" is the 19th of August in Mumbai and in Texas, and
+the moment you store it as a timestamp it stops being that.
+
+```js
+new Date('2026-08-19').getDate()
+// 19 in London
+// 18 in Los Angeles
+```
+
+That is a real bug, not a curiosity. It is why a film released on a Friday shows
+up as Thursday for some readers, why a "today" filter drops a row after 5pm, and
+why a report run in one office disagrees with the same report run in another.
+
+`calendardate` has no instant to get wrong. A date is `{ year, month, day }` and
+stays that way.
+
+## What it does
+
+```ts
+// parse and format, ISO 8601
+parseCalendarDate('2026-08-19') // { year: 2026, month: 8, day: 19 } | null
+formatIso(date) // '2026-08-19'
+isValidCalendarDate(value)
+
+// arithmetic
+addDays(date, 14)
+addMonths(date, -6) // clamps: 31 Aug − 6 months → 28 Feb
+daysInMonth(2026, 2)
+
+// comparison
+compareDates(a, b) // negative, zero, positive
+datesEqual(a, b)
+isWithin(date, start, end) // inclusive
+isSameMonth(a, b)
+
+// boundaries — weeks start Monday
+startOfWeek(date)
+endOfWeek(date)
+startOfMonth(date)
+endOfMonth(date)
+isoWeekday(date) // 1 Monday … 7 Sunday
+
+// the reader's own date
+todayInLocalTime()
+```
+
+## The one impure function
+
+`todayInLocalTime()` reads the system clock. Everything else is a pure function
+of its arguments.
+
+It is here because the alternative is worse: without it, every caller writes the
+same conversion from `Date` to a calendar date, and gets it subtly wrong. It
+takes an optional `Date` so a test can pass its own:
+
+```ts
+todayInLocalTime(new Date('2026-08-19T23:30:00-05:00')) // { year: 2026, month: 8, day: 19 }
+```
+
+## What it is not
+
+- **Not a time library.** No hours, no minutes, no timezones, no durations.
+  Reach for `Temporal` or `date-fns` when you need an instant.
+- **Not localised.** Nothing here produces a word. Month names and formatting
+  belong to whatever is doing the displaying, which knows the language.
+- **Not a `Date` replacement.** It is for the dates that were never instants in
+  the first place.
+
+## Should you use this?
+
+`Temporal.PlainDate` is the same idea, in the language itself, and it is landing
+in browsers. When you can rely on it, use it.
+
+Until then, or if you want something small with no dependencies and no
+polyfill, this does the job. It was extracted from a production site where the
+timezone bug above was a real one.
+
+## Weeks start on Monday
+
+`startOfWeek` and `isoWeekday` follow ISO 8601. There is no option to change it —
+an option would mean every caller deciding, and every caller deciding is how two
+parts of one system come to disagree about what week it is.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dyadav0607/calendardate",
+  "private": false,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.10"
+  },
+  "description": "Calendar dates without a timezone \u2014 a year, a month, a day, and the arithmetic that goes with them.",
+  "license": "MIT",
+  "keywords": [
+    "date",
+    "calendar",
+    "timezone",
+    "plain-date",
+    "civil-date",
+    "iso-8601"
+  ],
+  "files": [
+    "src/calendar.ts",
+    "src/calendarDate.ts",
+    "src/index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/calendar.ts

@@ -0,0 +1,142 @@
+import type { CalendarDate } from './calendarDate'
+
+/**
+ * Calendar arithmetic that never leaves the year/month/day frame.
+ *
+ * Every helper here that needs a JS `Date` constructs it with `Date.UTC` and
+ * reads it back with a `getUTC*` accessor. Mixing the two frames is what makes
+ * "2026-08-01" read back as July 31 west of UTC, which would put an entry in the
+ * wrong section for some viewers and no others.
+ */
+
+const MS_PER_DAY = 86_400_000
+
+function isPositiveInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value > 0
+}
+
+/** Days in a month, honouring leap years. */
+export function daysInMonth(year: number, month: number): number {
+  // Day 0 of the next month is the last day of this one. Constructed in UTC and
+  // read back in UTC, so no timezone shift can occur.
+  return new Date(Date.UTC(year, month, 0)).getUTCDate()
+}
+
+/**
+ * A calendar date is valid only if the day actually exists in that month, so
+ * 2026-02-30 is rejected rather than silently rolling over into March.
+ */
+export function isValidCalendarDate(value: unknown): value is CalendarDate {
+  if (typeof value !== 'object' || value === null) return false
+
+  const { year, month, day } = value as Partial<CalendarDate>
+  if (!isPositiveInteger(year) || !isPositiveInteger(month) || !isPositiveInteger(day)) {
+    return false
+  }
+  if (month > 12) return false
+
+  return day <= daysInMonth(year, month)
+}
+
+/**
+ * Parses an ISO-style `YYYY-MM-DD` string by reading its digits directly.
+ *
+ * Deliberately does not use `new Date(string)`: that parses to a UTC instant,
+ * and any later local-time read shifts the day.
+ */
+export function parseCalendarDate(value: string): CalendarDate | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value.trim())
+  if (!match) return null
+
+  const year = Number(match[1])
+  const month = Number(match[2])
+  const day = Number(match[3])
+
+  if (month < 1 || month > 12) return null
+  if (day < 1 || day > daysInMonth(year, month)) return null
+
+  return { year, month, day }
+}
+
+/** Formats a calendar date back to `YYYY-MM-DD`. */
+export function formatIso(date: CalendarDate): string {
+  const month = String(date.month).padStart(2, '0')
+  const day = String(date.day).padStart(2, '0')
+  return `${date.year}-${month}-${day}`
+}
+
+/** Negative when `a` is earlier, positive when later, zero when equal. */
+export function compareDates(a: CalendarDate, b: CalendarDate): number {
+  if (a.year !== b.year) return a.year - b.year
+  if (a.month !== b.month) return a.month - b.month
+  return a.day - b.day
+}
+
+export function datesEqual(a: CalendarDate, b: CalendarDate): boolean {
+  return compareDates(a, b) === 0
+}
+
+/** True when `date` falls within `start`..`end`, both inclusive. */
+export function isWithin(date: CalendarDate, start: CalendarDate, end: CalendarDate): boolean {
+  return compareDates(date, start) >= 0 && compareDates(date, end) <= 0
+}
+
+/** True when both dates fall in the same calendar month of the same year. */
+export function isSameMonth(a: CalendarDate, b: CalendarDate): boolean {
+  return a.year === b.year && a.month === b.month
+}
+
+/** Day of the week, 1 = Monday through 7 = Sunday. */
+export function isoWeekday(date: CalendarDate): number {
+  // getUTCDay gives 0 = Sunday; shift so Monday is 1 and Sunday is 7.
+  const sundayBased = new Date(Date.UTC(date.year, date.month - 1, date.day)).getUTCDay()
+  return sundayBased === 0 ? 7 : sundayBased
+}
+
+/** Moves `date` by `days`, which may be negative. Crosses month and year ends. */
+export function addDays(date: CalendarDate, days: number): CalendarDate {
+  const shifted = new Date(Date.UTC(date.year, date.month - 1, date.day) + days * MS_PER_DAY)
+  return {
+    year: shifted.getUTCFullYear(),
+    month: shifted.getUTCMonth() + 1,
+    day: shifted.getUTCDate(),
+  }
+}
+
+/**
+ * Moves `date` by `months`, clamping the day to the target month's length so
+ * that adding a month to January 31 gives the last day of February rather than
+ * rolling into March.
+ */
+export function addMonths(date: CalendarDate, months: number): CalendarDate {
+  const zeroBased = date.year * 12 + (date.month - 1) + months
+  const year = Math.floor(zeroBased / 12)
+  const month = (zeroBased % 12) + 1
+
+  return { year, month, day: Math.min(date.day, daysInMonth(year, month)) }
+}
+
+/** The Monday of the week containing `date`. */
+export function startOfWeek(date: CalendarDate): CalendarDate {
+  return addDays(date, -(isoWeekday(date) - 1))
+}
+
+/** The Sunday of the week containing `date`. */
+export function endOfWeek(date: CalendarDate): CalendarDate {
+  return addDays(date, 7 - isoWeekday(date))
+}
+
+export function startOfMonth(date: CalendarDate): CalendarDate {
+  return { year: date.year, month: date.month, day: 1 }
+}
+
+export function endOfMonth(date: CalendarDate): CalendarDate {
+  return { year: date.year, month: date.month, day: daysInMonth(date.year, date.month) }
+}
+
+/** Reads today's date from the system clock in the viewer's local timezone. */
+export function todayInLocalTime(now: Date = new Date()): CalendarDate {
+  // Local accessors throughout: the viewer's own calendar day is what "today"
+  // means here, so this is the one place local time is intentional.
+  return { year: now.getFullYear(), month: now.getMonth() + 1, day: now.getDate() }
+}

package/src/calendarDate.ts

@@ -0,0 +1,20 @@
+/**
+ * A calendar date with no time-of-day and no timezone.
+ *
+ * Release dates are calendar dates, not instants: an entry dated 2026-08-01 must
+ * group as 2026-08-01 for every viewer regardless of their timezone. Representing
+ * dates as year/month/day fields keeps them out of the JS `Date` type, where
+ * parsing "2026-08-01" yields a UTC midnight instant that reads back as July 31
+ * anywhere west of UTC.
+ *
+ * Lives in `shared/` because nothing about it is film-specific: any feature
+ * dealing in dates — watchlists, reminders — wants the same representation.
+ */
+export interface CalendarDate {
+  /** Four-digit year. */
+  readonly year: number
+  /** 1-12, January is 1. */
+  readonly month: number
+  /** 1-31. */
+  readonly day: number
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Calendar dates without a timezone.
+ *
+ * A release date is not an instant. "Released on 19 August" is true in Mumbai
+ * and in Texas, and representing it as a timestamp makes it drift by a day
+ * depending on where the reader is. Everything here works on a plain
+ * `{ year, month, day }` instead.
+ *
+ * No dependencies, no words, no policy — only arithmetic and parsing.
+ */
+
+export type { CalendarDate } from './calendarDate'
+
+export {
+  addDays,
+  addMonths,
+  compareDates,
+  datesEqual,
+  daysInMonth,
+  endOfMonth,
+  endOfWeek,
+  formatIso,
+  isoWeekday,
+  isSameMonth,
+  isValidCalendarDate,
+  isWithin,
+  parseCalendarDate,
+  startOfMonth,
+  startOfWeek,
+  todayInLocalTime,
+} from './calendar'