{"_id":"temporal-utils","_rev":"6-2463641354c548f9511408a59faa8314","name":"temporal-utils","dist-tags":{"latest":"1.0.3"},"versions":{"1.0.0":{"name":"temporal-utils","version":"1.0.0","author":"","license":"ISC","_id":"temporal-utils@1.0.0","maintainers":[{"name":"arshaw","email":"arshaw@arshaw.com"}],"dist":{"shasum":"857133f0ee6208118d4c2026f2a4233a390cb7aa","tarball":"https://registry.npmjs.org/temporal-utils/-/temporal-utils-1.0.0.tgz","fileCount":1,"integrity":"sha512-+7Eg/qU/9KATuaZK41Mh7boBPZYUxMKQMVyLagfto0jgTOSeTiYOYp136PPX9GaWl40r/C+kIIk+Iuwm5YYrFg==","signatures":[{"sig":"MEQCIBuRcHu6Fe4Fu8A8zkgzkHDE7vFtw4IfBRulARq2yBqjAiBccjonGpiPH9uW+fQn3D6NVhRPY4KVcVWIjTb40HafiA==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}],"unpackedSize":210,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.13\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJgrvWCCRA9TVsSAnZWagAAQN8P+QD4MNlUu9oW0ztoYeUF\nPUIvpgH2sacnn5kSOe74piwqzKC6YXZbyB5XTCdPSEFhgmrqNGT05tFKVbOy\n20Mt+1CCV63f+ZviFk5dpuoi/a2rTLiPREpow4SHvBZBwGzV0gFa7iyich9S\nU0/L7Zyy1xZKN5iff/+XuLJui+F7Hkdq9GSNEn22kOJem6jOxaw3XnAiHAMI\nM4twWf/cl5jrokyLfY3k0IWDEKkDGPTMyYccEFuzq9OOrO+GsNpHPAFRYKWE\nHWFErRCkYkgXMVsfAOnqCcUBNAFGJkDSPFUuPu9N43W5syJDKCFtjwDj7TW6\nVyJ/DrZtwM2pOw3SFWGvxX+m8/2oqUIy37jNlZTYAbwRaUZy6UhsIV+krrOB\nQj4kC/dvdit/rWn8V9BtCFnnlyOmFnvdX0lgPiVWOs2SZJcfPt7+gdIO1AdZ\niY7N386QrycNYzNULkgVnCPk73aqVzwVWrdheM6cGInq1Ld/xw8saK/NKt73\nHZtgZTBKMO7FM9GyX0YvBJ2kPyVrFHDMPFwRl6fWxdniRd+yiZPYvP0uen8M\nqB/u3vSiphrnqSQ8IQ+xyjOIhQ6Bq+5YalOGkdUKZxQgLY68hBJTjCp3cxYZ\nRZQJxmpYMsOhdyNM+KJQ3uLiEhSr8V/jQ52arAcIklLtn0zN0lyLch0vDF1v\n702U\r\n=4JGz\r\n-----END PGP SIGNATURE-----\r\n"},"main":"index.js","scripts":{"test":"echo \"Error: no test specified\" && exit 1"},"_npmUser":{"name":"arshaw","email":"arshaw@arshaw.com"},"deprecated":"Accidental empty publish — do not use","_npmVersion":"6.14.12","description":"","directories":{},"_nodeVersion":"14.16.1","_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/temporal-utils_1.0.0_1622078849810_0.29228231647625913","host":"s3://npm-registry-packages"}},"1.0.1":{"name":"temporal-utils","version":"1.0.1","author":{"url":"http://arshaw.com/","name":"Adam Shaw","email":"arshaw@users.noreply.github.com"},"license":"MIT","_id":"temporal-utils@1.0.1","maintainers":[{"name":"arshaw","email":"arshaw@arshaw.com"}],"homepage":"https://github.com/fullcalendar/temporal-polyfill#readme","bugs":{"url":"https://github.com/fullcalendar/temporal-polyfill/issues"},"dist":{"shasum":"faf276e216512ccd1575a4705a58d73a091aeb82","tarball":"https://registry.npmjs.org/temporal-utils/-/temporal-utils-1.0.1.tgz","fileCount":25,"integrity":"sha512-HAixuesxFQIUaQk3ptX2jhfO/FsOkgVkDDMawvp6n/fkB1q6BKfs3lURw9I+pK/2e2e/q/vrLrxmeqauBoyGMQ==","signatures":[{"sig":"MEUCIE4jZHqkcPWlUKH5Mo+xoeWiKksE/oPQeU1UdZ0Tz8tgAiEAj9jO5RGlW8VVJ5PFxE0hRuhFxJs6pUhAASDke+rWd6o=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48576},"main":"./dist/index.js","type":"module","_from":"file:temporal-utils-1.0.1.tgz","title":"Temporal Utils","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./protected":{"types":"./dist/protected.d.ts","import":"./dist/protected.js"},"./protected-error-messages":{"types":"./dist/protected-error-messages.d.ts","import":"./dist/protected-error-messages.js"}},"scripts":{"dev":"pnpm run clean && tsc --build tsconfig.dev.json --watch","lint":"biome check .","test":"pnpm run vitest","build":"pnpm run clean && tsc --build tsconfig.build.json","clean":"rm -rf dist","vitest":"./scripts/vitest.js","lint:fix":"biome check --apply .","vitest:dev":"vitest dev","vitest:debug":"vitest run --no-isolate --no-file-parallelism --test-timeout 3600000"},"_npmUser":{"name":"arshaw","email":"arshaw@arshaw.com"},"_resolved":"/private/var/folders/8f/41dg5l5910zdh4ytckn8swt80000gn/T/0ae139015cbd0a3069335a020e481088/temporal-utils-1.0.1.tgz","copyright":"2026 Adam Shaw","_integrity":"sha512-HAixuesxFQIUaQk3ptX2jhfO/FsOkgVkDDMawvp6n/fkB1q6BKfs3lURw9I+pK/2e2e/q/vrLrxmeqauBoyGMQ==","repository":{"url":"git+https://github.com/fullcalendar/temporal-polyfill.git","type":"git","directory":"utils"},"_npmVersion":"11.12.1","description":"Convenience helpers for native Temporal objects","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.2.2","typescript":"~5.3.3","temporal-spec":"1.0.0","@biomejs/biome":"1.5.1","@js-temporal/polyfill":"^0.5.1"},"_npmOperationalInternal":{"tmp":"tmp/temporal-utils_1.0.1_1781828737250_0.09781741924965681","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"temporal-utils","version":"1.0.2","author":{"url":"http://arshaw.com/","name":"Adam Shaw","email":"arshaw@users.noreply.github.com"},"license":"MIT","_id":"temporal-utils@1.0.2","maintainers":[{"name":"arshaw","email":"arshaw@arshaw.com"}],"homepage":"https://github.com/fullcalendar/temporal-polyfill#readme","bugs":{"url":"https://github.com/fullcalendar/temporal-polyfill/issues"},"dist":{"shasum":"a9f27b645fdf503e469dfb4df8c421d697079dbd","tarball":"https://registry.npmjs.org/temporal-utils/-/temporal-utils-1.0.2.tgz","fileCount":25,"integrity":"sha512-1B8Dl4KzrOvsNUlpoWGno2VLQlxroLjDgc5NBjVC9ax9ymdo+ezfyvhyjEMx+IVfhINr6CIG2gcnlP95iRrybQ==","signatures":[{"sig":"MEYCIQD92mh6AAoqTfiTvnA7StAaUIudDd64uLyDtJHZJF9wWgIhANxjjA5pDJQbsBWDahHd8qO8ELmUOtFB1kPRkFPpS3C2","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":48311},"main":"./dist/index.js","type":"module","_from":"file:temporal-utils-1.0.2.tgz","title":"Temporal Utils","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./protected":{"types":"./dist/protected.d.ts","default":"./dist/protected.js"},"./protected-error-messages":{"types":"./dist/protected-error-messages.d.ts","default":"./dist/protected-error-messages.js"}},"scripts":{"dev":"pnpm run clean && tsc --build tsconfig.dev.json --watch","lint":"biome check .","test":"pnpm run vitest","build":"pnpm run clean && tsc --build tsconfig.build.json","clean":"rm -rf dist","vitest":"./scripts/vitest.js","lint:fix":"biome check --apply .","vitest:dev":"vitest dev","vitest:debug":"vitest run --no-isolate --no-file-parallelism --test-timeout 3600000"},"_npmUser":{"name":"arshaw","email":"arshaw@arshaw.com"},"_resolved":"/private/var/folders/8f/41dg5l5910zdh4ytckn8swt80000gn/T/63a964d0dcd37bdd2c21f07a83476f3d/temporal-utils-1.0.2.tgz","copyright":"2026 Adam Shaw","_integrity":"sha512-1B8Dl4KzrOvsNUlpoWGno2VLQlxroLjDgc5NBjVC9ax9ymdo+ezfyvhyjEMx+IVfhINr6CIG2gcnlP95iRrybQ==","repository":{"url":"git+https://github.com/fullcalendar/temporal-polyfill.git","type":"git","directory":"utils"},"_npmVersion":"11.12.1","description":"Convenience helpers for native Temporal objects","directories":{},"_nodeVersion":"24.15.0","_hasShrinkwrap":false,"devDependencies":{"vitest":"^1.2.2","typescript":"~5.3.3","temporal-spec":"1.0.1","@biomejs/biome":"1.5.1","@js-temporal/polyfill":"^0.5.1"},"_npmOperationalInternal":{"tmp":"tmp/temporal-utils_1.0.2_1786639919993_0.7756179986859677","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"temporal-utils","version":"1.0.3","title":"Temporal Utils","description":"Convenience helpers for native Temporal objects","author":{"name":"Adam Shaw","email":"arshaw@users.noreply.github.com","url":"http://arshaw.com/"},"license":"MIT","copyright":"2026 Adam Shaw","repository":{"type":"git","url":"git+https://github.com/fullcalendar/temporal-polyfill.git","directory":"utils"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./protected":{"types":"./dist/protected.d.ts","default":"./dist/protected.js"},"./protected-error-messages":{"types":"./dist/protected-error-messages.d.ts","default":"./dist/protected-error-messages.js"}},"type":"module","devDependencies":{"@biomejs/biome":"1.5.1","@js-temporal/polyfill":"^0.5.1","typescript":"~5.3.3","vitest":"^1.2.2","temporal-spec":"1.0.1"},"scripts":{"build":"pnpm run clean && tsc --build tsconfig.build.json","dev":"pnpm run clean && tsc --build tsconfig.dev.json --watch","lint":"biome check .","lint:fix":"biome check --apply .","test":"pnpm run vitest","vitest":"./scripts/vitest.js","vitest:dev":"vitest dev","vitest:debug":"vitest run --no-isolate --no-file-parallelism --test-timeout 3600000","clean":"rm -rf dist"},"_id":"temporal-utils@1.0.3","bugs":{"url":"https://github.com/fullcalendar/temporal-polyfill/issues"},"homepage":"https://github.com/fullcalendar/temporal-polyfill#readme","_integrity":"sha512-9jbTSX3HvkOWvDpNpFzwX/d1mkCrgQgwLmVTOEiuocZGKHsrQJtttGZFmybJ2zYP5zCSZuU5ZyeS8+eOEPABiQ==","_resolved":"/private/var/folders/8f/41dg5l5910zdh4ytckn8swt80000gn/T/b328f9acc286da9e255fe89ede22c697/temporal-utils-1.0.3.tgz","_from":"file:temporal-utils-1.0.3.tgz","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-9jbTSX3HvkOWvDpNpFzwX/d1mkCrgQgwLmVTOEiuocZGKHsrQJtttGZFmybJ2zYP5zCSZuU5ZyeS8+eOEPABiQ==","shasum":"dbbe3e14adaa81fcf811d0f7380b30a9c6a2ada0","tarball":"https://registry.npmjs.org/temporal-utils/-/temporal-utils-1.0.3.tgz","fileCount":25,"unpackedSize":48849,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIA9VgfxfOgf10rUiytaFxVqqWwjQfGZSjg/0CqBzz7r7AiBHB1qHw+94TRfrbn0wBofC8jEl8ZOie102nZV4vyRABw=="}]},"_npmUser":{"name":"arshaw","email":"arshaw@arshaw.com"},"directories":{},"maintainers":[{"name":"arshaw","email":"arshaw@arshaw.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/temporal-utils_1.0.3_1789158283128_0.9783063837567516"},"_hasShrinkwrap":false}},"time":{"created":"2021-05-27T01:27:29.809Z","modified":"2026-09-11T20:24:43.460Z","1.0.0":"2021-05-27T01:27:29.973Z","1.0.1":"2026-06-19T00:25:37.379Z","1.0.2":"2026-08-13T16:52:00.148Z","1.0.3":"2026-09-11T20:24:43.316Z"},"bugs":{"url":"https://github.com/fullcalendar/temporal-polyfill/issues"},"author":{"name":"Adam Shaw","email":"arshaw@users.noreply.github.com","url":"http://arshaw.com/"},"license":"MIT","homepage":"https://github.com/fullcalendar/temporal-polyfill#readme","repository":{"type":"git","url":"git+https://github.com/fullcalendar/temporal-polyfill.git","directory":"utils"},"description":"Convenience helpers for native Temporal objects","maintainers":[{"name":"arshaw","email":"arshaw@arshaw.com"}],"readme":"# temporal-utils\n\nSmall, application-level helpers for working with native [Temporal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal) objects\n\nMost helpers preserve the input type. For example, passing a\n`Temporal.PlainDateTime` to `startOfMonth` returns a `Temporal.PlainDateTime`,\nwhile passing a `Temporal.ZonedDateTime` returns a `Temporal.ZonedDateTime`.\n\n## Installation\n\n```\nnpm install temporal-utils\n```\n\n`temporal-utils` does not ship a Temporal implementation of its own — a global\n`Temporal` must already exist at runtime. See [Requirements](#requirements).\n\n## Usage\n\nImport the helpers you need from the package root and call them on native\nTemporal objects. Each helper accepts a range of Temporal types and gives you\nback the same type you passed in:\n\n```ts\nimport { startOfMonth, diffDays } from 'temporal-utils'\n\n// Pass a PlainDate, get a PlainDate back\nstartOfMonth(Temporal.PlainDate.from('2024-07-20')).toString()\n// '2024-07-01'\n\n// Pass a ZonedDateTime, get a ZonedDateTime back\nstartOfMonth(\n  Temporal.ZonedDateTime.from('2024-07-20T12:30[America/New_York]'),\n).toString()\n// '2024-07-01T00:00:00-04:00[America/New_York]'\n\ndiffDays(\n  Temporal.PlainDate.from('2024-07-01'),\n  Temporal.PlainDate.from('2024-07-20'),\n)\n// 19\n```\n\n## Requirements\n\n`temporal-utils` operates on native `Temporal` objects but does **not** include\na Temporal implementation of its own. A global `Temporal` must already exist at\nruntime — note that every example below references `Temporal.*` directly to\nbuild its inputs. Ensure one is present in one of two ways:\n\n- **Native `Temporal`** — available in newer browsers and runtimes, but support\n  is still rolling out and remains incomplete.\n- **A polyfill** — recommended for now. We suggest\n  [`temporal-polyfill`](https://github.com/fullcalendar/temporal-polyfill/blob/main/polyfill/README.md), which installs a global\n  `Temporal`:\n\n  ```ts\n  import 'temporal-polyfill/global'\n  ```\n\n## Function Reference\n\n- [Field Replacement](#field-replacement)\n  - [`withDayOfYear`](#withdayofyear)\n  - [`withDayOfWeek`](#withdayofweek)\n  - [`withWeekOfYear`](#withweekofyear)\n- [Difference Helpers](#difference-helpers)\n  - [`diffYears`](#diffyears)\n  - [`diffMonths`](#diffmonths)\n  - [`diffWeeks`](#diffweeks)\n  - [`diffDays`](#diffdays)\n  - [`diffHours`](#diffhours)\n  - [`diffMinutes`](#diffminutes)\n  - [`diffSeconds`](#diffseconds)\n  - [`diffMilliseconds`](#diffmilliseconds)\n  - [`diffMicroseconds`](#diffmicroseconds)\n  - [`diffNanoseconds`](#diffnanoseconds)\n- [Rounding Helpers](#rounding-helpers)\n  - [`roundToYear`](#roundtoyear)\n  - [`roundToMonth`](#roundtomonth)\n  - [`roundToWeek`](#roundtoweek)\n  - [⚠️ `roundToDay`](#roundtoday)\n  - [⚠️ `roundToHour`](#roundtohour)\n  - [⚠️ `roundToMinute`](#roundtominute)\n  - [⚠️ `roundToSecond`](#roundtosecond)\n  - [⚠️ `roundToMillisecond`](#roundtomillisecond)\n  - [⚠️ `roundToMicrosecond`](#roundtomicrosecond)\n- [Start Of Unit](#start-of-unit)\n  - [`startOfYear`](#startofyear)\n  - [`startOfMonth`](#startofmonth)\n  - [`startOfWeek`](#startofweek)\n  - [`startOfDay`](#startofday)\n  - [`startOfHour`](#startofhour)\n  - [`startOfMinute`](#startofminute)\n  - [`startOfSecond`](#startofsecond)\n  - [`startOfMillisecond`](#startofmillisecond)\n  - [`startOfMicrosecond`](#startofmicrosecond)\n- [End Of Unit](#end-of-unit)\n  - [`endOfYear`](#endofyear)\n  - [`endOfMonth`](#endofmonth)\n  - [`endOfWeek`](#endofweek)\n  - [`endOfDay`](#endofday)\n  - [`endOfHour`](#endofhour)\n  - [`endOfMinute`](#endofminute)\n  - [`endOfSecond`](#endofsecond)\n  - [`endOfMillisecond`](#endofmillisecond)\n  - [`endOfMicrosecond`](#endofmicrosecond)\n- [Shared Types](#shared-types)\n  - [`RoundingMode`](#roundingmode)\n  - [`RoundingMathOptions`](#roundingmathoptions)\n\n## Field Replacement\n\nThese helpers fill gaps where Temporal exposes calendar-derived fields such as\n`dayOfYear`, `dayOfWeek`, and `weekOfYear`, but does not provide direct\n`with({ ... })` fields for replacing them.\n\nAll field replacement helpers:\n\n- accept `Temporal.PlainDate`, `Temporal.PlainDateTime`, or\n  `Temporal.ZonedDateTime`\n- truncate numeric input toward zero before applying it\n- accept Temporal field overflow options: `{ overflow: 'constrain' }` or\n  `{ overflow: 'reject' }`\n- default overflow behavior to `'constrain'`\n\n### `withDayOfYear`\n\nSignature:\n\n```ts\nfunction withDayOfYear<\n  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(\n  date: T,\n  dayOfYear: number,\n  options?: Temporal.OverflowOptions,\n): T\n```\n\nReturns the same calendar year with `dayOfYear` replaced. The time, time zone,\nand calendar are preserved.\n\n```ts\nimport { withDayOfYear } from 'temporal-utils'\n\nconst date = Temporal.PlainDate.from('2024-02-27')\n\nwithDayOfYear(date, 5).toString()\n// '2024-01-05'\n\nwithDayOfYear(date, 500).toString()\n// '2024-12-31'\n\nwithDayOfYear(date, 500, { overflow: 'reject' })\n// RangeError\n```\n\n### `withDayOfWeek`\n\nSignature:\n\n```ts\nfunction withDayOfWeek<\n  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(\n  date: T,\n  dayOfWeek: number,\n  options?: Temporal.OverflowOptions,\n): T\n```\n\nReturns the same ISO week with `dayOfWeek` replaced. Temporal uses ISO weekday\nnumbers: Monday is `1` and Sunday is `7`.\n\n```ts\nimport { withDayOfWeek } from 'temporal-utils'\n\nconst date = Temporal.PlainDate.from('2024-02-27') // Tuesday\n\nwithDayOfWeek(date, 4).toString()\n// '2024-02-29'\n\nwithDayOfWeek(date, 8).toString()\n// '2024-03-03'\n```\n\n### `withWeekOfYear`\n\nSignature:\n\n```ts\nfunction withWeekOfYear<\n  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(\n  date: T,\n  weekOfYear: number,\n  options?: Temporal.OverflowOptions,\n): T\n```\n\nReturns the same ISO week-year with `weekOfYear` replaced, preserving the\ncurrent day of week. This helper is ISO-only and throws a `RangeError` for\ncalendars where Temporal does not expose ISO week fields.\n\n```ts\nimport { withWeekOfYear } from 'temporal-utils'\n\nconst date = Temporal.PlainDate.from('2024-02-27') // Tuesday, week 9\n\nwithWeekOfYear(date, 27).toString()\n// '2024-07-02'\n\nwithWeekOfYear(date.withCalendar('hebrew'), 27)\n// RangeError\n```\n\n## Difference Helpers\n\nSingle-unit difference helpers return a number for `date0.until(date1)`. The\nhelpers are directional: reversing the arguments reverses the sign.\n\nIf no options are supplied, the result is the exact total in the requested unit.\nPass a `RoundingMode` string or a `RoundingMathOptions` object to request Temporal\nrounding behavior for that unit.\n\n```ts\nimport { diffDays, diffMonths } from 'temporal-utils'\n\nconst start = Temporal.PlainDate.from('2024-02-20')\nconst end = Temporal.PlainDate.from('2024-04-10')\n\ndiffMonths(start, end)\n// approximately 1.677...\n\ndiffMonths(start, end, 'floor')\n// 1\n\ndiffDays(start, end, { roundingMode: 'ceil', roundingIncrement: 7 })\n// 56\n```\n\nDate and calendar unit helpers use `relativeTo` internally so totals account\nfor calendar units. For `Temporal.ZonedDateTime`, totals also account for\ntime-zone transitions. Time-unit helpers produce elapsed-time totals.\n\n### `diffYears`\n\nSignature:\n\n```ts\nfunction diffYears(\n  date0: Temporal.PlainYearMonth | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  date1: Temporal.PlainYearMonth | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  options?: RoundingMode | RoundingMathOptions,\n): number\n```\n\nReturns the difference in years. Supported input types are\n`Temporal.PlainYearMonth`, `Temporal.PlainDate`, `Temporal.PlainDateTime`, and\n`Temporal.ZonedDateTime`.\n\n### `diffMonths`\n\nSignature:\n\n```ts\nfunction diffMonths(\n  date0: Temporal.PlainYearMonth | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  date1: Temporal.PlainYearMonth | Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  options?: RoundingMode | RoundingMathOptions,\n): number\n```\n\nReturns the difference in months. Supported input types are\n`Temporal.PlainYearMonth`, `Temporal.PlainDate`, `Temporal.PlainDateTime`, and\n`Temporal.ZonedDateTime`.\n\n### `diffWeeks`\n\nSignature:\n\n```ts\nfunction diffWeeks(\n  date0: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  date1: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  options?: RoundingMode | RoundingMathOptions,\n): number\n```\n\nReturns the difference in weeks. Supported input types are `Temporal.PlainDate`,\n`Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.\n\n### `diffDays`\n\nSignature:\n\n```ts\nfunction diffDays(\n  date0: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  date1: Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  options?: RoundingMode | RoundingMathOptions,\n): number\n```\n\nReturns the difference in days. Supported input types are `Temporal.PlainDate`,\n`Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.\n\n### `diffHours`\n\nSignature:\n\n```ts\nfunction diffHours(\n  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  options?: RoundingMode | RoundingMathOptions,\n): number\n```\n\nReturns the difference in hours. Supported input types are `Temporal.Instant`,\n`Temporal.PlainTime`, `Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.\n\n### `diffMinutes`\n\nSignature:\n\n```ts\nfunction diffMinutes(\n  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  options?: RoundingMode | RoundingMathOptions,\n): number\n```\n\nReturns the difference in minutes. Supported input types are `Temporal.Instant`,\n`Temporal.PlainTime`, `Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.\n\n### `diffSeconds`\n\nSignature:\n\n```ts\nfunction diffSeconds(\n  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  options?: RoundingMode | RoundingMathOptions,\n): number\n```\n\nReturns the difference in seconds. Supported input types are `Temporal.Instant`,\n`Temporal.PlainTime`, `Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.\n\n### `diffMilliseconds`\n\nSignature:\n\n```ts\nfunction diffMilliseconds(\n  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  options?: RoundingMode | RoundingMathOptions,\n): number\n```\n\nReturns the difference in milliseconds. Supported input types are\n`Temporal.Instant`, `Temporal.PlainTime`, `Temporal.PlainDateTime`, and\n`Temporal.ZonedDateTime`.\n\n### `diffMicroseconds`\n\nSignature:\n\n```ts\nfunction diffMicroseconds(\n  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  options?: RoundingMode | RoundingMathOptions,\n): number\n```\n\nReturns the difference in microseconds. Supported input types are\n`Temporal.Instant`, `Temporal.PlainTime`, `Temporal.PlainDateTime`, and\n`Temporal.ZonedDateTime`.\n\n### `diffNanoseconds`\n\nSignature:\n\n```ts\nfunction diffNanoseconds(\n  date0: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  date1: Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n  options?: RoundingMode | RoundingMathOptions,\n): number\n```\n\nReturns the difference in nanoseconds. Supported input types are\n`Temporal.Instant`, `Temporal.PlainTime`, `Temporal.PlainDateTime`, and\n`Temporal.ZonedDateTime`.\n\n## Rounding Helpers\n\nCalendar rounding helpers return the closest start of the named unit. They are\nuseful because Temporal's native `.round()` APIs cover day and smaller units,\nbut not every larger calendar unit in a uniform way across date-like types.\n\nIf `options` or `options.roundingMode` is omitted, `roundingMode` defaults to\n`'halfExpand'`. Pass a `RoundingMode` string as shorthand for\n`{ roundingMode }`.\n\n`RoundingMathOptions` must not include `smallestUnit`; the helper name supplies\nthe unit. For the year, month, and week helpers, `roundingIncrement` must be\nomitted or `1`.\n\n⚠️ The day and smaller `roundTo*` helpers are exported as codemod targets, not\nas recommended hand-written API. In application code, prefer native Temporal\n`.round()` directly:\n\n```ts\ndateTime.round({ smallestUnit: 'day' })\ntime.round({ smallestUnit: 'minute', roundingMode: 'ceil' })\ninstant.round({ smallestUnit: 'second' })\n```\n\n```ts\nimport { roundToMonth, roundToWeek, roundToYear } from 'temporal-utils'\n\nconst dateTime = Temporal.PlainDateTime.from('2024-07-20T12:30:00')\n\nroundToYear(dateTime).toString()\n// '2025-01-01T00:00:00'\n\nroundToMonth(dateTime, 'floor').toString()\n// '2024-07-01T00:00:00'\n\nroundToWeek(dateTime, { roundingMode: 'floor' }).toString()\n// '2024-07-15T00:00:00'\n```\n\n### `roundToYear`\n\nSignature:\n\n```ts\nfunction roundToYear<\n  T extends\n    | Temporal.PlainYearMonth\n    | Temporal.PlainDate\n    | Temporal.PlainDateTime\n    | Temporal.ZonedDateTime,\n>(date: T, options?: RoundingMode | RoundingMathOptions): T\n```\n\nRounds to the nearest year boundary. Supported input types are\n`Temporal.PlainYearMonth`, `Temporal.PlainDate`, `Temporal.PlainDateTime`, and\n`Temporal.ZonedDateTime`.\n\n### `roundToMonth`\n\nSignature:\n\n```ts\nfunction roundToMonth<\n  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T, options?: RoundingMode | RoundingMathOptions): T\n```\n\nRounds to the nearest month boundary. Supported input types are\n`Temporal.PlainDate`, `Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.\n\n### `roundToWeek`\n\nSignature:\n\n```ts\nfunction roundToWeek<\n  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T, options?: RoundingMode | RoundingMathOptions): T\n```\n\nRounds to the nearest ISO week boundary. Supported input types are\n`Temporal.PlainDate`, `Temporal.PlainDateTime`, and `Temporal.ZonedDateTime`.\n\n<a id=\"roundtoday\"></a>\n\n### ⚠️ `roundToDay`\n\nSignature:\n\n```ts\nfunction roundToDay<T extends Temporal.PlainDateTime | Temporal.ZonedDateTime>(\n  date: T,\n  options?: RoundingMode | RoundingMathOptions,\n): T\n```\n\nCodemod target for rounding to the nearest day. Prefer\n`dateTime.round({ smallestUnit: 'day' })` in hand-written code.\n\n<a id=\"roundtohour\"></a>\n\n### ⚠️ `roundToHour`\n\nSignature:\n\n```ts\nfunction roundToHour<\n  T extends Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T, options?: RoundingMode | RoundingMathOptions): T\n```\n\nCodemod target for rounding to the nearest hour. Prefer\n`value.round({ smallestUnit: 'hour' })` in hand-written code.\n\n<a id=\"roundtominute\"></a>\n\n### ⚠️ `roundToMinute`\n\nSignature:\n\n```ts\nfunction roundToMinute<\n  T extends Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T, options?: RoundingMode | RoundingMathOptions): T\n```\n\nCodemod target for rounding to the nearest minute. Prefer\n`value.round({ smallestUnit: 'minute' })` in hand-written code.\n\n<a id=\"roundtosecond\"></a>\n\n### ⚠️ `roundToSecond`\n\nSignature:\n\n```ts\nfunction roundToSecond<\n  T extends Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T, options?: RoundingMode | RoundingMathOptions): T\n```\n\nCodemod target for rounding to the nearest second. Prefer\n`value.round({ smallestUnit: 'second' })` in hand-written code.\n\n<a id=\"roundtomillisecond\"></a>\n\n### ⚠️ `roundToMillisecond`\n\nSignature:\n\n```ts\nfunction roundToMillisecond<\n  T extends Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T, options?: RoundingMode | RoundingMathOptions): T\n```\n\nCodemod target for rounding to the nearest millisecond. Prefer\n`value.round({ smallestUnit: 'millisecond' })` in hand-written code.\n\n<a id=\"roundtomicrosecond\"></a>\n\n### ⚠️ `roundToMicrosecond`\n\nSignature:\n\n```ts\nfunction roundToMicrosecond<\n  T extends Temporal.Instant | Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T, options?: RoundingMode | RoundingMathOptions): T\n```\n\nCodemod target for rounding to the nearest microsecond. Prefer\n`value.round({ smallestUnit: 'microsecond' })` in hand-written code.\n\n## Start Of Unit\n\nStart helpers truncate smaller fields to the beginning of the named unit.\n`startOfWeek` uses ISO weeks, so the week starts on Monday.\n\nFor `Temporal.ZonedDateTime`, these helpers use Temporal's own field\nreplacement behavior. If local midnight is skipped by a time-zone transition,\nTemporal resolves to the first real instant after the skipped wall time.\n\n```ts\nimport { startOfMonth, startOfWeek } from 'temporal-utils'\n\nconst zdt = Temporal.ZonedDateTime.from('2024-07-20T12:30:00[America/New_York]')\n\nstartOfMonth(zdt).toString()\n// '2024-07-01T00:00:00-04:00[America/New_York]'\n\nstartOfWeek(zdt).toString()\n// '2024-07-15T00:00:00-04:00[America/New_York]'\n```\n\n### `startOfYear`\n\nSignature:\n\n```ts\nfunction startOfYear<\n  T extends\n    | Temporal.PlainYearMonth\n    | Temporal.PlainDate\n    | Temporal.PlainDateTime\n    | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the start of the current year. For `Temporal.PlainYearMonth`, this is\nJanuary of the same year.\n\n### `startOfMonth`\n\nSignature:\n\n```ts\nfunction startOfMonth<\n  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the start of the current month.\n\n### `startOfWeek`\n\nSignature:\n\n```ts\nfunction startOfWeek<\n  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the start of the current ISO week, which is Monday.\n\n### `startOfDay`\n\nSignature:\n\n```ts\nfunction startOfDay<T extends Temporal.PlainDateTime | Temporal.ZonedDateTime>(\n  dateTime: T,\n): T\n```\n\nReturns midnight at the start of the current day.\n\n### `startOfHour`\n\nSignature:\n\n```ts\nfunction startOfHour<\n  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(dateTime: T): T\n```\n\nReturns the start of the current hour.\n\n### `startOfMinute`\n\nSignature:\n\n```ts\nfunction startOfMinute<\n  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(dateTime: T): T\n```\n\nReturns the start of the current minute.\n\n### `startOfSecond`\n\nSignature:\n\n```ts\nfunction startOfSecond<\n  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(dateTime: T): T\n```\n\nReturns the start of the current second.\n\n### `startOfMillisecond`\n\nSignature:\n\n```ts\nfunction startOfMillisecond<\n  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(dateTime: T): T\n```\n\nReturns the start of the current millisecond.\n\n### `startOfMicrosecond`\n\nSignature:\n\n```ts\nfunction startOfMicrosecond<\n  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(dateTime: T): T\n```\n\nReturns the start of the current microsecond.\n\n## End Of Unit\n\nEnd helpers return the last representable value before the next unit begins.\nFor date-time and zoned date-time values, this means one nanosecond before the\nexclusive end. For date-only values, it means one day before the exclusive end.\nFor `Temporal.PlainYearMonth`, `endOfYear` returns December of the same year.\n\n```ts\nimport { endOfDay, endOfMonth } from 'temporal-utils'\n\nconst dateTime = Temporal.PlainDateTime.from('2024-07-20T12:30:00')\n\nendOfDay(dateTime).toString()\n// '2024-07-20T23:59:59.999999999'\n\nendOfMonth(dateTime).toString()\n// '2024-07-31T23:59:59.999999999'\n```\n\n### `endOfYear`\n\nSignature:\n\n```ts\nfunction endOfYear<\n  T extends\n    | Temporal.PlainYearMonth\n    | Temporal.PlainDate\n    | Temporal.PlainDateTime\n    | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the last representable value in the current year.\n\n### `endOfMonth`\n\nSignature:\n\n```ts\nfunction endOfMonth<\n  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the last representable value in the current month.\n\n### `endOfWeek`\n\nSignature:\n\n```ts\nfunction endOfWeek<\n  T extends Temporal.PlainDate | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the last representable value in the current ISO week.\n\n### `endOfDay`\n\nSignature:\n\n```ts\nfunction endOfDay<T extends Temporal.PlainDateTime | Temporal.ZonedDateTime>(\n  date: T,\n): T\n```\n\nReturns the last representable value in the current day.\n\n### `endOfHour`\n\nSignature:\n\n```ts\nfunction endOfHour<\n  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the last representable value in the current hour.\n\n### `endOfMinute`\n\nSignature:\n\n```ts\nfunction endOfMinute<\n  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the last representable value in the current minute.\n\n### `endOfSecond`\n\nSignature:\n\n```ts\nfunction endOfSecond<\n  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the last representable value in the current second.\n\n### `endOfMillisecond`\n\nSignature:\n\n```ts\nfunction endOfMillisecond<\n  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the last representable value in the current millisecond.\n\n### `endOfMicrosecond`\n\nSignature:\n\n```ts\nfunction endOfMicrosecond<\n  T extends Temporal.PlainTime | Temporal.PlainDateTime | Temporal.ZonedDateTime,\n>(date: T): T\n```\n\nReturns the last representable value in the current microsecond.\n\n## Shared Types\n\n### `RoundingMode`\n\nType:\n\n```ts\nimport type { RoundingMode } from 'temporal-utils'\n```\n\n`RoundingMode` is shared by the rounding and difference helpers.\n\n### `RoundingMathOptions`\n\nType:\n\n```ts\nimport type { RoundingMathOptions } from 'temporal-utils'\n```\n\n`RoundingMathOptions` contains the rounding fields used by single-unit math\nhelpers.\n\nThe unit is implied by the helper name. For example, `roundToWeek(date,\noptions)` forces `smallestUnit: 'week'` internally, and `diffMonths(date0,\ndate1, options)` forces month-based difference math internally.\n","readmeFilename":"README.md"}