{"id":27008950,"url":"https://github.com/xurei/plain-date-js","last_synced_at":"2026-04-15T18:01:50.524Z","repository":{"id":274122750,"uuid":"921964601","full_name":"xurei/plain-date-js","owner":"xurei","description":"Lightweight, simple library for handling dates without the complexities of timezones, time components, or some of the more subtle aspects of date manipulation.","archived":false,"fork":false,"pushed_at":"2025-01-26T17:16:23.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-20T20:41:06.307Z","etag":null,"topics":["date","js","plain","ts"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/xurei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-01-25T00:54:55.000Z","updated_at":"2025-01-26T17:16:26.000Z","dependencies_parsed_at":null,"dependency_job_id":"1ca639cf-4a76-4a4f-a65c-3551867e65c4","html_url":"https://github.com/xurei/plain-date-js","commit_stats":null,"previous_names":["xurei/plain-date-js"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/xurei/plain-date-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xurei%2Fplain-date-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xurei%2Fplain-date-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xurei%2Fplain-date-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xurei%2Fplain-date-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xurei","download_url":"https://codeload.github.com/xurei/plain-date-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xurei%2Fplain-date-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31853279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["date","js","plain","ts"],"created_at":"2025-04-04T09:18:29.990Z","updated_at":"2026-04-15T18:01:50.517Z","avatar_url":"https://github.com/xurei.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PlainDate\nA lightweight, simple library for handling dates without the ~~headaches~~ complexities of dates.\n\n[![codecov](https://codecov.io/gh/xurei/plain-date-js/branch/main/graph/badge.svg?token=59DRZOTEPW)](https://codecov.io/gh/xurei/plain-date-js)\n![NPM Version](https://img.shields.io/npm/v/@xureilab/plain-date)\n\nIt allows you to work with \"plain\" dates, where the focus is entirely on the day, month, and year, leaving out \ncomplications such as hours, minutes, seconds, timezones, and other intricacies.\n\nThe library provides a unique class, `PlainDate`, with helper functions to compare dates, convert from/to ISO strings or \nvanilla JS `Date` objects.\n\nThis library is perfect for applications that need basic date operations, such as adding days, \nchecking if a date is within a range, or converting dates from ISO strings.  \nIf you need more complex operations (*e.g.* working with time, timezones, or other detailed date manipulations), \nyou should consider using PlainDate alongside libraries like [date-fns](https://www.npmjs.com/package/date-fns), \n[luxon](https://www.npmjs.com/package/luxon), or [moment.js](https://www.npmjs.com/package/moment).\n\n## Key Features\n- **No Timezone**: All dates are based purely on the calendar day, month, and year, without the complications of timezones.\n- **Simple Date Arithmetic**: Add or subtract days from a date.\n- **ISO String Parsing**: Parse ISO date strings into a PlainDate object.\n- **Date Comparison**: Compare dates (before, after, equal).\n- **Date Range Check**: Check if a date is within a given date range.\n- **Leap Year Handling**: Automatically accounts for leap years when adding/subtracting days or working with months.\n- **Fully tested**: See the [Codecov](https://app.codecov.io/gh/xurei/plain-date-js) page for details.\n- **No dependency**: Because no one likes that.\n\n## Installation\n```bash\nnpm install @xureilab/plain-date\n```\n\n## Why use PlainDate ?\nIf you've ever worked with dates in any programming language, you're probably familiar \nwith the ~~headaches~~ complexity involved.   \nTimezones, varying days in months, leap years, even leap seconds... there are countless pitfalls that can trip you up.\n\nHowever, in many cases, you don't **need** or even **want** a full-fledged `Date` object.  \nWhat you really need is a reliable object that represents **a day** — just **a day**, not a precise moment in time.\n\nThis library was built with that purpose in mind: to offer a simple, intuitive way of handling **days** without all the \ncomplications of timezones, time, and calendar nuances.\n\nFeatures that would require arbitrary decisions or assumptions aren't — and won't —\nbe implemented.  \nFor example:\n\n- **Adding one month to `2023-03-31`**: Should it return `2023-04-30` or `2023-05-01`?\n- **Adding one year to `2024-02-29`**: Should it return `2025-02-28` or `2025-03-01`?\n\nThese are subjective design choices that depend on the specific needs of your software.\nInstead of forcing you into one decision, this library leaves those kinds of questions to be solved in\nyour own application logic.\n\nThe end goal of this library is to **simplify date handling**. The fewer complications there are, the easier it is to \nmentally process and reason about dates. `PlainDate` is designed to make working with dates more straightforward, \nless confusing.  \nIn the end, it makes it easier to handle dates without getting bogged down by unnecessary complexity,\nand avoid unexpected corner cases.\n\nUltimately, the simpler you can make the problem, the easier it becomes to think about it.\n\n## Usage\n### Create a PlainDate\n#### Explicitly\n```typescript\nimport { PlainDate } from '@xureilab/plain-date';\n\nconst date = new PlainDate(2024, 2, 15);\nconsole.log(date); // PlainDate { year: 2024, month: 2, day: 15 }\n```\n\n#### Convert from ISO String\n```typescript\nconst date = PlainDate.fromISOString('2024-02-15');\nconsole.log(date); // PlainDate { year: 2024, month: 2, day: 15 }\n```\nIf the ISO string is invalid, it will throw an error, unless you provide a fallback `PlainDate`:\n```typescript\nconst fallbackDate = new PlainDate(2023, 12, 31);\nconst date = PlainDate.fromISOString('invalid-date', fallbackDate);\nconsole.log(date); // PlainDate { year: 2023, month: 12, day: 31 }\n```\n\n#### Get the current day (using local timezone)\n```typescript\nconst date = PlainDate.today();\n```\n\n#### From a JS `Date` object (using local timezone)\n```typescript\nconst jsDate = new Date(/* ... */);\nconst date = PlainDate.fromJSDate(jsDate);\n```\n\n#### From a JS `Date` object (using UTC timezone)\n```typescript\nconst jsDate = new Date(/* ... */);\nconst date = PlainDate.fromUTCJSDate(jsDate);\n```\n\n### Adding or Subtracting Days\nYou can easily add or subtract days from a PlainDate:\n```typescript\nconst date = new PlainDate(2024, 2, 15);\nconst newDate = date.addDays(5); // Adds 5 days\nconsole.log(newDate); // PlainDate { year: 2024, month: 2, day: 20 }\n\nconst previousDate = date.subDays(10); // Subtracts 10 days\nconsole.log(previousDate); // PlainDate { year: 2024, month: 2, day: 5 }\n```\n\n### Checking Validity\nYou can check if a date is valid by calling the isValid() method:\n```typescript\nconst date = new PlainDate(2024, 2, 29);\nconsole.log(date.isValid()); // true (2024 is a leap year)\n```\n\n### Comparing Dates\n```typescript\nconst date1 = new PlainDate(2024, 2, 15);\nconst date2 = new PlainDate(2024, 2, 16);\nconsole.log(date1.isEqual(date2));  // false\nconsole.log(date1.isBefore(date2)); // true\nconsole.log(date1.isBeforeOrEqual(date2));  // true\nconsole.log(date1.isAfter(date2));  // false\nconsole.log(date1.isAfterOrEqual(date2));  // false\n```\n\n### Date Range Check (inclusive)\n```typescript\nconst date = new PlainDate(2024, 2, 15);\nconst from = new PlainDate(2024, 2, 10);\nconst to = new PlainDate(2024, 2, 20);\n\nconsole.log(date.isInInterval(from, to)); // true\n````\n\n### Getting the difference in days\n```typescript\nconsole.log(new PlainDate(2024, 2, 15).getDaysDifference(new PlainDate(2024, 2, 1))); // -14\nconsole.log(new PlainDate(2024, 3, 5).getDaysDifference(new PlainDate(2024, 3, 20))); // 15\nconsole.log(new PlainDate(2024, 1, 15).getDaysDifference(new PlainDate(2025, 1, 15))); // 366 since 2024 is a leap year\n```\n\n### Getting the Day of the Week\n```typescript\nconst date = new PlainDate(2024, 2, 15);\nconsole.log(date.getDayOfWeek()); // 5 (Friday)\nconsole.log(date.getDayOfWeekStr()); // \"Friday\"\n```\n\n### Convert to JS Date\nBy convention, returned JS Dates are set at midnight.\n\n#### Local timezone\n```typescript\nconst date = new PlainDate(2024, 2, 15);\nconsole.log(date.toJSDate()); // 2024-02-15T04:00:00.000Z in New York timezone\n```\n\n#### UTC timezone\n```typescript\nconst date = new PlainDate(2024, 2, 15);\nconsole.log(date.toUTCJSDate()); // 2024-02-15T00:00:00.000Z in UTC timezone\n```\n\n## License\nMIT License. See the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxurei%2Fplain-date-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxurei%2Fplain-date-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxurei%2Fplain-date-js/lists"}