@gobrand/tiempo 2.2.3 → 2.3.1

package/README.md

@@ -1,10 +1,10 @@
-# tiempo
+# @gobrand/tiempo
 
 [![npm version](https://img.shields.io/npm/v/@gobrand/tiempo.svg)](https://www.npmjs.com/package/@gobrand/tiempo)
 [![CI](https://github.com/go-brand/tiempo/actions/workflows/ci.yml/badge.svg)](https://github.com/go-brand/tiempo/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-Lightweight utilities for timezones and datetimes with the [Temporal API](https://tc39.es/proposal-temporal/docs/).
+Comprehensive datetime utilities for the [Temporal API](https://tc39.es/proposal-temporal/docs/). Full timezone support, nanosecond precision, and 54+ utility functions with a familiar API.
 
 ## Installation
 
@@ -18,26 +18,53 @@ yarn add @gobrand/tiempo
 
 ## Why tiempo?
 
-The Temporal API is powerful but requires understanding its various methods and objects. `tiempo` provides intuitive utilities for common datetime tasks: timezone conversions, formatting, start/end calculations, and comparisons. Whether you're converting UTC strings from your backend or formatting dates for display, tiempo makes working with timezones straightforward.
+The Temporal API is powerful but requires understanding its various methods and objects. **tiempo** (`@gobrand/tiempo`) provides 54+ intuitive utilities for every datetime task:
+
+- **🌍 Timezone conversions** - Convert between UTC and any timezone effortlessly
+- **➕ Complete arithmetic** - Add/subtract any time unit from nanoseconds to years
+- **📅 Calendar operations** - Start/end of day, week, month, year with DST handling
+- **🔍 Comparisons** - Check if dates are before, after, same day, future, or past
+- **📊 Differences** - Calculate precise differences in any time unit
+- **🎨 Formatting** - Format dates with date-fns-style tokens or Intl
+- **⚡️ Type-safe** - Full TypeScript support with proper Temporal types
+- **🎯 Zero config** - Simple, direct function signatures
+
+**Key features:**
+- ✅ Native timezone support with Temporal API
+- ✅ DST transitions handled automatically
+- ✅ Nanosecond precision (beyond milliseconds)
+- ✅ Calendar-aware arithmetic (leap years, month-end dates)
+- ✅ Familiar date-fns-style API, built for the future
 
 **Perfect for:**
 - Social media scheduling apps
 - Calendar applications
 - Booking systems
+- Time tracking tools
+- Analytics dashboards
 - Any app that needs to handle user timezones
 
 ## Quick Start
 
 ```typescript
-import { toZonedTime, toUtcString } from '@gobrand/tiempo';
+import { toZonedTime, toUtcString, toUtc, toDate } from '@gobrand/tiempo';
 
-// Backend sends: "2025-01-20T20:00:00.000Z"
+// From ISO string (typical backend API)
 const zoned = toZonedTime("2025-01-20T20:00:00.000Z", "America/New_York");
 console.log(zoned.hour); // 15 (3 PM in New York)
 
-// Send back to backend:
-const utc = toUtcString(zoned);
-console.log(utc); // "2025-01-20T20:00:00Z"
+// From Date object (e.g., Drizzle ORM)
+const date = new Date("2025-01-20T20:00:00.000Z");
+const zonedFromDate = toZonedTime(date, "America/New_York");
+console.log(zonedFromDate.hour); // 15 (3 PM in New York)
+
+// Back to ISO string
+const utcString = toUtcString(zoned);
+console.log(utcString); // "2025-01-20T20:00:00Z"
+
+// Back to Date object (for Drizzle ORM)
+const backToDate = toDate(zoned);
+console.log(backToDate.toISOString()); // "2025-01-20T20:00:00.000Z"
 ```
 
 ## API
@@ -46,10 +73,10 @@ console.log(utc); // "2025-01-20T20:00:00Z"
 
 #### `toZonedTime(input, timezone)`
 
-Convert a UTC ISO string, Instant, or ZonedDateTime to a ZonedDateTime in the specified timezone.
+Convert a UTC ISO string, Date, Instant, or ZonedDateTime to a ZonedDateTime in the specified timezone.
 
 **Parameters:**
-- `input` (string | Temporal.Instant | Temporal.ZonedDateTime): A UTC ISO 8601 string, Temporal.Instant, or Temporal.ZonedDateTime
+- `input` (string | Date | Temporal.Instant | Temporal.ZonedDateTime): A UTC ISO 8601 string, Date object, Temporal.Instant, or Temporal.ZonedDateTime
 - `timezone` (string): An IANA timezone identifier (e.g., `"America/New_York"`, `"Europe/London"`)
 
 **Returns:** `Temporal.ZonedDateTime` - The same instant in the specified timezone
@@ -63,9 +90,14 @@ const zoned = toZonedTime("2025-01-20T20:00:00.000Z", "America/New_York");
 console.log(zoned.hour); // 15 (3 PM in New York)
 console.log(zoned.toString()); // "2025-01-20T15:00:00-05:00[America/New_York]"
 
+// From Date (e.g., from Drizzle ORM)
+const date = new Date("2025-01-20T20:00:00.000Z");
+const zoned2 = toZonedTime(date, "America/New_York");
+console.log(zoned2.hour); // 15 (3 PM in New York)
+
 // From Instant
 const instant = Temporal.Instant.from("2025-01-20T20:00:00Z");
-const zoned2 = toZonedTime(instant, "Asia/Tokyo");
+const zoned3 = toZonedTime(instant, "Asia/Tokyo");
 
 // From ZonedDateTime (convert to different timezone)
 const nyTime = Temporal.ZonedDateTime.from("2025-01-20T15:00:00-05:00[America/New_York]");
@@ -74,10 +106,10 @@ const tokyoTime = toZonedTime(nyTime, "Asia/Tokyo");
 
 #### `toUtc(input)`
 
-Convert a UTC ISO string or ZonedDateTime to a Temporal.Instant (UTC).
+Convert a UTC ISO string, Date, or ZonedDateTime to a Temporal.Instant (UTC).
 
 **Parameters:**
-- `input` (string | Temporal.ZonedDateTime): A UTC ISO 8601 string or Temporal.ZonedDateTime
+- `input` (string | Date | Temporal.ZonedDateTime): A UTC ISO 8601 string, Date object, or Temporal.ZonedDateTime
 
 **Returns:** `Temporal.Instant` - A Temporal.Instant representing the same moment in UTC
 
@@ -88,10 +120,14 @@ import { toUtc } from '@gobrand/tiempo';
 // From ISO string
 const instant = toUtc("2025-01-20T20:00:00.000Z");
 
+// From Date (e.g., from Drizzle ORM)
+const date = new Date("2025-01-20T20:00:00.000Z");
+const instant2 = toUtc(date);
+
 // From ZonedDateTime
 const zoned = Temporal.ZonedDateTime.from("2025-01-20T15:00:00-05:00[America/New_York]");
-const instant2 = toUtc(zoned);
-// Both represent the same UTC moment: 2025-01-20T20:00:00Z
+const instant3 = toUtc(zoned);
+// All represent the same UTC moment: 2025-01-20T20:00:00Z
 ```
 
 #### `toUtcString(input)`
@@ -118,6 +154,35 @@ const iso2 = toUtcString(instant);
 console.log(iso2); // "2025-01-20T20:00:00Z"
 ```
 
+#### `toDate(input)`
+
+Convert a Temporal.Instant or ZonedDateTime to a Date object.
+
+**Parameters:**
+- `input` (Temporal.Instant | Temporal.ZonedDateTime): A Temporal.Instant or Temporal.ZonedDateTime
+
+**Returns:** `Date` - A Date object representing the same moment in time
+
+**Example:**
+```typescript
+import { toDate } from '@gobrand/tiempo';
+
+// From Instant
+const instant = Temporal.Instant.from("2025-01-20T20:00:00Z");
+const date = toDate(instant);
+console.log(date.toISOString()); // "2025-01-20T20:00:00.000Z"
+
+// From ZonedDateTime
+const zoned = Temporal.ZonedDateTime.from("2025-01-20T15:00:00-05:00[America/New_York]");
+const date2 = toDate(zoned);
+console.log(date2.toISOString()); // "2025-01-20T20:00:00.000Z"
+
+// Use with Drizzle ORM (for storing back to database)
+const instant = Temporal.Instant.from("2025-01-20T20:00:00Z");
+const dateForDb = toDate(instant);
+await db.update(posts).set({ publishedAt: dateForDb });
+```
+
 ### Formatting
 
 #### `intlFormatDistance(laterDate, earlierDate, options?)`
@@ -346,6 +411,138 @@ startOfYear(zoned); // 2025-01-01T00:00:00-05:00[America/New_York]
 endOfYear(zoned);   // 2025-12-31T23:59:59.999999999-05:00[America/New_York]
 ```
 
+### Addition/Subtraction Utilities
+
+tiempo provides comprehensive datetime arithmetic functions for all time units, from nanoseconds to years. All functions:
+- Accept `Temporal.Instant` or `Temporal.ZonedDateTime` as input
+- Return `Temporal.ZonedDateTime` preserving the original timezone
+- Properly handle DST transitions, leap years, and month-end edge cases
+- Support negative values for subtraction
+
+#### Addition Functions
+
+##### `addYears(input, years)` / `addMonths(input, months)` / `addWeeks(input, weeks)` / `addDays(input, days)`
+
+Add calendar units (years, months, weeks, or days) to a datetime.
+
+```typescript
+import { addYears, addMonths, addWeeks, addDays } from '@gobrand/tiempo';
+
+const date = Temporal.Instant.from('2025-01-20T12:00:00Z');
+
+addYears(date, 2);   // 2027-01-20T12:00:00Z[UTC] (2 years later)
+addMonths(date, 3);  // 2025-04-20T12:00:00Z[UTC] (3 months later)
+addWeeks(date, 2);   // 2025-02-03T12:00:00Z[UTC] (2 weeks later)
+addDays(date, 5);    // 2025-01-25T12:00:00Z[UTC] (5 days later)
+
+// Handle month-end edge cases automatically
+const endOfJan = Temporal.Instant.from('2025-01-31T12:00:00Z');
+addMonths(endOfJan, 1); // 2025-02-28T12:00:00Z[UTC] (Jan 31 → Feb 28)
+
+// Negative values subtract
+addMonths(date, -3); // 2024-10-20T12:00:00Z[UTC] (3 months earlier)
+```
+
+##### `addHours(input, hours)` / `addMinutes(input, minutes)` / `addSeconds(input, seconds)`
+
+Add time units (hours, minutes, or seconds) to a datetime.
+
+```typescript
+import { addHours, addMinutes, addSeconds } from '@gobrand/tiempo';
+
+const time = Temporal.Instant.from('2025-01-20T12:00:00Z');
+
+addHours(time, 3);    // 2025-01-20T15:00:00Z[UTC] (3 hours later)
+addMinutes(time, 30); // 2025-01-20T12:30:00Z[UTC] (30 minutes later)
+addSeconds(time, 45); // 2025-01-20T12:00:45Z[UTC] (45 seconds later)
+
+// Works with ZonedDateTime and preserves timezone
+const ny = Temporal.ZonedDateTime.from('2025-01-20T15:00:00-05:00[America/New_York]');
+addHours(ny, 2); // 2025-01-20T17:00:00-05:00[America/New_York]
+```
+
+##### `addMilliseconds(input, ms)` / `addMicroseconds(input, μs)` / `addNanoseconds(input, ns)`
+
+Add sub-second precision units (milliseconds, microseconds, or nanoseconds) to a datetime.
+
+```typescript
+import { addMilliseconds, addMicroseconds, addNanoseconds } from '@gobrand/tiempo';
+
+const precise = Temporal.Instant.from('2025-01-20T12:00:00Z');
+
+addMilliseconds(precise, 500); // 2025-01-20T12:00:00.500Z[UTC]
+addMicroseconds(precise, 500); // 2025-01-20T12:00:00.000500Z[UTC]
+addNanoseconds(precise, 500);  // 2025-01-20T12:00:00.000000500Z[UTC]
+```
+
+#### Subtraction Functions
+
+All subtraction functions are convenience wrappers that call their corresponding addition functions with negated values.
+
+##### `subYears(input, years)` / `subMonths(input, months)` / `subWeeks(input, weeks)` / `subDays(input, days)`
+
+```typescript
+import { subYears, subMonths, subWeeks, subDays } from '@gobrand/tiempo';
+
+const date = Temporal.Instant.from('2025-01-20T12:00:00Z');
+
+subYears(date, 2);  // 2023-01-20T12:00:00Z[UTC] (2 years earlier)
+subMonths(date, 3); // 2024-10-20T12:00:00Z[UTC] (3 months earlier)
+subWeeks(date, 2);  // 2025-01-06T12:00:00Z[UTC] (2 weeks earlier)
+subDays(date, 5);   // 2025-01-15T12:00:00Z[UTC] (5 days earlier)
+```
+
+##### `subHours(input, hours)` / `subMinutes(input, minutes)` / `subSeconds(input, seconds)`
+
+```typescript
+import { subHours, subMinutes, subSeconds } from '@gobrand/tiempo';
+
+const time = Temporal.Instant.from('2025-01-20T12:00:00Z');
+
+subHours(time, 3);    // 2025-01-20T09:00:00Z[UTC] (3 hours earlier)
+subMinutes(time, 30); // 2025-01-20T11:30:00Z[UTC] (30 minutes earlier)
+subSeconds(time, 45); // 2025-01-20T11:59:15Z[UTC] (45 seconds earlier)
+```
+
+##### `subMilliseconds(input, ms)` / `subMicroseconds(input, μs)` / `subNanoseconds(input, ns)`
+
+```typescript
+import { subMilliseconds, subMicroseconds, subNanoseconds } from '@gobrand/tiempo';
+
+const precise = Temporal.Instant.from('2025-01-20T12:00:00.500Z');
+
+subMilliseconds(precise, 250); // 2025-01-20T12:00:00.250Z[UTC]
+subMicroseconds(precise, 250); // 2025-01-20T12:00:00.499750Z[UTC]
+subNanoseconds(precise, 250);  // 2025-01-20T12:00:00.499999750Z[UTC]
+```
+
+#### Real-world Example: Meeting Scheduler
+
+```typescript
+import {
+  toZonedTime,
+  addDays,
+  addMinutes,
+  format
+} from '@gobrand/tiempo';
+
+// User's current meeting time
+const meeting = toZonedTime('2025-01-20T15:00:00Z', 'America/New_York');
+// 2025-01-20T10:00:00-05:00[America/New_York] (10 AM in NY)
+
+// Reschedule to tomorrow, same time
+const tomorrow = addDays(meeting, 1);
+format(tomorrow, 'EEEE, MMMM do'); // "Tuesday, January 21st"
+
+// Add 30-minute buffer before the meeting
+const arriveBy = subMinutes(tomorrow, 30);
+format(arriveBy, 'h:mm a'); // "9:30 AM"
+
+// Schedule follow-up 2 weeks later
+const followUp = addWeeks(tomorrow, 2);
+format(followUp, 'MMM d'); // "Feb 4"
+```
+
 ### Comparison Utilities
 
 #### `isBefore(date1, date2)` / `isAfter(date1, date2)`
@@ -550,12 +747,51 @@ const instant2 = Temporal.Instant.from('2025-01-20T23:00:00Z');
 isSameDay(instant1, instant2); // true (both Jan 20 in UTC)
 ```
 
-## Real World Example
+## Drizzle ORM Integration
+
+tiempo seamlessly integrates with Drizzle ORM for database datetime operations. When using Drizzle with PostgreSQL `timestamptz` columns and `mode: 'date'`, tiempo provides utilities to convert between Date objects and Temporal.
+
+```typescript
+import { toZonedTime, toUtc, toDate } from '@gobrand/tiempo';
+
+// 1. Reading from database (Drizzle returns Date with mode: 'date')
+const post = await db.query.posts.findFirst();
+const publishedAt = post.publishedAt; // Date object
+
+// 2. Convert to user's timezone for display
+const userTimezone = "America/New_York";
+const zonedTime = toZonedTime(publishedAt, userTimezone);
+console.log(zonedTime.hour); // Local hour in user's timezone
+
+// 3. User reschedules post to tomorrow at 3 PM their time
+const rescheduled = zonedTime.add({ days: 1 }).with({ hour: 15, minute: 0 });
+
+// 4. Convert back to Date for database storage
+const dateForDb = toDate(rescheduled);
+await db.update(posts).set({ publishedAt: dateForDb }).where(eq(posts.id, post.id));
+```
+
+**Why this works:**
+- Drizzle's `mode: 'date'` returns JavaScript `Date` objects (timestamps)
+- `toZonedTime(date, tz)` converts the Date to a timezone-aware Temporal object
+- Work with Temporal's powerful API for date arithmetic and manipulation
+- `toDate(temporal)` converts back to Date for Drizzle storage
+
+## Real World Examples
 
-This example demonstrates the complete workflow of working with datetimes in a frontend application: receiving a UTC ISO 8601 string from your backend, converting it to a Temporal object in the user's timezone, formatting it for display, manipulating it based on user input, and sending it back to your backend as a UTC ISO 8601 string.
+### Example 1: Social Media Post Scheduler
+
+This example demonstrates the complete workflow of working with datetimes in a frontend application: receiving a UTC ISO 8601 string from your backend, converting it to a Temporal object in the user's timezone, formatting it for display, manipulating it with tiempo's arithmetic functions, and sending it back to your backend as a UTC ISO 8601 string.
 
 ```typescript
-import { toZonedTime, toUtcString, format } from '@gobrand/tiempo';
+import {
+  toZonedTime,
+  toUtcString,
+  format,
+  addDays,
+  addHours,
+  subMinutes
+} from '@gobrand/tiempo';
 
 // 1. Receive UTC ISO 8601 string from backend
 const scheduledAtUTC = "2025-01-20T20:00:00.000Z";
@@ -568,16 +804,53 @@ const zonedDateTime = toZonedTime(scheduledAtUTC, userTimezone);
 const displayTime = format(zonedDateTime, "EEEE, MMMM do 'at' h:mm a");
 console.log(displayTime); // "Monday, January 20th at 3:00 PM"
 
-// 4. User reschedules to 4:00 PM their time
-const updatedZoned = zonedDateTime.with({ hour: 16 });
+// 4. User wants to reschedule to tomorrow, 2 hours later
+const tomorrow = addDays(zonedDateTime, 1);
+const twoHoursLater = addHours(tomorrow, 2);
 
 // 5. Format the updated time for confirmation
-const confirmTime = format(updatedZoned, "h:mm a");
-console.log(`Rescheduled to ${confirmTime}`); // "Rescheduled to 4:00 PM"
+const confirmTime = format(twoHoursLater, "EEEE 'at' h:mm a");
+console.log(`Rescheduled to ${confirmTime}`); // "Tuesday at 5:00 PM"
 
 // 6. Convert back to UTC ISO 8601 string for backend
-const updatedUTC = toUtcString(updatedZoned);
-console.log(updatedUTC); // "2025-01-20T21:00:00Z"
+const updatedUTC = toUtcString(twoHoursLater);
+console.log(updatedUTC); // "2025-01-21T22:00:00Z"
+```
+
+### Example 2: Meeting Reminder System
+
+```typescript
+import {
+  toZonedTime,
+  format,
+  subMinutes,
+  subHours,
+  differenceInMinutes,
+  isFuture
+} from '@gobrand/tiempo';
+
+// Meeting scheduled for 2 PM
+const meeting = toZonedTime('2025-01-20T19:00:00Z', 'America/New_York');
+// 2025-01-20T14:00:00-05:00[America/New_York]
+
+// Send reminders at multiple intervals
+const reminders = [
+  { time: subMinutes(meeting, 15), label: '15 minutes before' },
+  { time: subHours(meeting, 1), label: '1 hour before' },
+  { time: subHours(meeting, 24), label: '1 day before' },
+];
+
+reminders.forEach(({ time, label }) => {
+  if (isFuture(time)) {
+    const formatted = format(time, 'MMM d, h:mm a');
+    console.log(`Send reminder "${label}" at ${formatted}`);
+  }
+});
+
+// Calculate time until meeting
+const now = Temporal.Now.zonedDateTimeISO('America/New_York');
+const minutesUntil = differenceInMinutes(meeting, now);
+console.log(`Meeting starts in ${minutesUntil} minutes`);
 ```
 
 ## Browser Support

package/dist/addDays.d.ts

@@ -0,0 +1,37 @@
+import type { Temporal } from '@js-temporal/polyfill';
+/**
+ * Adds the specified number of days to a datetime.
+ *
+ * Properly handles DST transitions and calendar edge cases through Temporal API.
+ * Instant inputs are converted to UTC. For ZonedDateTime inputs, their timezone is preserved.
+ *
+ * @param input - A Temporal.Instant (UTC) or Temporal.ZonedDateTime
+ * @param days - Number of days to add (can be negative to subtract)
+ * @returns ZonedDateTime with days added, in the same timezone as input
+ *
+ * @example
+ * ```ts
+ * // From Instant (always UTC)
+ * const instant = Temporal.Instant.from('2025-01-20T12:00:00Z');
+ * const result = addDays(instant, 5);
+ * // 2025-01-25T12:00:00Z[UTC] (5 days later)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // From ZonedDateTime (preserves timezone)
+ * const zoned = Temporal.ZonedDateTime.from('2025-01-20T15:30:00-05:00[America/New_York]');
+ * const result = addDays(zoned, 10);
+ * // 2025-01-30T15:30:00-05:00[America/New_York]
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Negative values subtract days
+ * const instant = Temporal.Instant.from('2025-01-20T12:00:00Z');
+ * const result = addDays(instant, -7);
+ * // 2025-01-13T12:00:00Z[UTC] (7 days earlier)
+ * ```
+ */
+export declare function addDays(input: Temporal.Instant | Temporal.ZonedDateTime, days: number): Temporal.ZonedDateTime;
+//# sourceMappingURL=addDays.d.ts.map

package/dist/addDays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addDays.d.ts","sourceRoot":"","sources":["../src/addDays.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,OAAO,CACrB,KAAK,EAAE,QAAQ,CAAC,OAAO,GAAG,QAAQ,CAAC,aAAa,EAChD,IAAI,EAAE,MAAM,GACX,QAAQ,CAAC,aAAa,CAGxB"}

package/dist/addDays.js

@@ -0,0 +1,8 @@
+import {
+  addDays
+} from "./chunk-L4SVABDH.js";
+import "./chunk-MJSZNWCV.js";
+export {
+  addDays
+};
+//# sourceMappingURL=addDays.js.map

package/dist/addDays.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/addDays.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=addDays.test.d.ts.map

package/dist/addDays.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addDays.test.d.ts","sourceRoot":"","sources":["../src/addDays.test.ts"],"names":[],"mappings":""}

package/dist/addHours.d.ts

@@ -0,0 +1,37 @@
+import type { Temporal } from '@js-temporal/polyfill';
+/**
+ * Adds the specified number of hours to a datetime.
+ *
+ * Properly handles DST transitions through Temporal API.
+ * Instant inputs are converted to UTC. For ZonedDateTime inputs, their timezone is preserved.
+ *
+ * @param input - A Temporal.Instant (UTC) or Temporal.ZonedDateTime
+ * @param hours - Number of hours to add (can be negative to subtract)
+ * @returns ZonedDateTime with hours added, in the same timezone as input
+ *
+ * @example
+ * ```ts
+ * // From Instant (always UTC)
+ * const instant = Temporal.Instant.from('2025-01-20T12:00:00Z');
+ * const result = addHours(instant, 3);
+ * // 2025-01-20T15:00:00Z[UTC] (3 hours later)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // From ZonedDateTime (preserves timezone)
+ * const zoned = Temporal.ZonedDateTime.from('2025-01-20T15:30:00-05:00[America/New_York]');
+ * const result = addHours(zoned, 24);
+ * // 2025-01-21T15:30:00-05:00[America/New_York]
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Negative values subtract hours
+ * const instant = Temporal.Instant.from('2025-01-20T12:00:00Z');
+ * const result = addHours(instant, -5);
+ * // 2025-01-20T07:00:00Z[UTC] (5 hours earlier)
+ * ```
+ */
+export declare function addHours(input: Temporal.Instant | Temporal.ZonedDateTime, hours: number): Temporal.ZonedDateTime;
+//# sourceMappingURL=addHours.d.ts.map

package/dist/addHours.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addHours.d.ts","sourceRoot":"","sources":["../src/addHours.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,QAAQ,CACtB,KAAK,EAAE,QAAQ,CAAC,OAAO,GAAG,QAAQ,CAAC,aAAa,EAChD,KAAK,EAAE,MAAM,GACZ,QAAQ,CAAC,aAAa,CAGxB"}

package/dist/addHours.js

@@ -0,0 +1,8 @@
+import {
+  addHours
+} from "./chunk-4NJMCCUM.js";
+import "./chunk-MJSZNWCV.js";
+export {
+  addHours
+};
+//# sourceMappingURL=addHours.js.map

package/dist/addHours.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/addHours.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=addHours.test.d.ts.map

package/dist/addHours.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addHours.test.d.ts","sourceRoot":"","sources":["../src/addHours.test.ts"],"names":[],"mappings":""}

package/dist/addMicroseconds.d.ts

@@ -0,0 +1,36 @@
+import type { Temporal } from '@js-temporal/polyfill';
+/**
+ * Adds the specified number of microseconds to a datetime.
+ *
+ * Instant inputs are converted to UTC. For ZonedDateTime inputs, their timezone is preserved.
+ *
+ * @param input - A Temporal.Instant (UTC) or Temporal.ZonedDateTime
+ * @param microseconds - Number of microseconds to add (can be negative to subtract)
+ * @returns ZonedDateTime with microseconds added, in the same timezone as input
+ *
+ * @example
+ * ```ts
+ * // From Instant (always UTC)
+ * const instant = Temporal.Instant.from('2025-01-20T12:00:00Z');
+ * const result = addMicroseconds(instant, 500);
+ * // 2025-01-20T12:00:00.000500Z[UTC] (500 microseconds later)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // From ZonedDateTime (preserves timezone)
+ * const zoned = Temporal.ZonedDateTime.from('2025-01-20T15:30:00-05:00[America/New_York]');
+ * const result = addMicroseconds(zoned, 1000);
+ * // 2025-01-20T15:30:00.001-05:00[America/New_York]
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Negative values subtract microseconds
+ * const instant = Temporal.Instant.from('2025-01-20T12:00:00.001Z');
+ * const result = addMicroseconds(instant, -500);
+ * // 2025-01-20T12:00:00.000500Z[UTC] (500 microseconds earlier)
+ * ```
+ */
+export declare function addMicroseconds(input: Temporal.Instant | Temporal.ZonedDateTime, microseconds: number): Temporal.ZonedDateTime;
+//# sourceMappingURL=addMicroseconds.d.ts.map

package/dist/addMicroseconds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addMicroseconds.d.ts","sourceRoot":"","sources":["../src/addMicroseconds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,QAAQ,CAAC,OAAO,GAAG,QAAQ,CAAC,aAAa,EAChD,YAAY,EAAE,MAAM,GACnB,QAAQ,CAAC,aAAa,CAGxB"}

package/dist/addMicroseconds.js

@@ -0,0 +1,8 @@
+import {
+  addMicroseconds
+} from "./chunk-V27NUBXQ.js";
+import "./chunk-MJSZNWCV.js";
+export {
+  addMicroseconds
+};
+//# sourceMappingURL=addMicroseconds.js.map

package/dist/addMicroseconds.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/addMicroseconds.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=addMicroseconds.test.d.ts.map

package/dist/addMicroseconds.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addMicroseconds.test.d.ts","sourceRoot":"","sources":["../src/addMicroseconds.test.ts"],"names":[],"mappings":""}

package/dist/addMilliseconds.d.ts

@@ -0,0 +1,36 @@
+import type { Temporal } from '@js-temporal/polyfill';
+/**
+ * Adds the specified number of milliseconds to a datetime.
+ *
+ * Instant inputs are converted to UTC. For ZonedDateTime inputs, their timezone is preserved.
+ *
+ * @param input - A Temporal.Instant (UTC) or Temporal.ZonedDateTime
+ * @param milliseconds - Number of milliseconds to add (can be negative to subtract)
+ * @returns ZonedDateTime with milliseconds added, in the same timezone as input
+ *
+ * @example
+ * ```ts
+ * // From Instant (always UTC)
+ * const instant = Temporal.Instant.from('2025-01-20T12:00:00Z');
+ * const result = addMilliseconds(instant, 500);
+ * // 2025-01-20T12:00:00.500Z[UTC] (500 milliseconds later)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // From ZonedDateTime (preserves timezone)
+ * const zoned = Temporal.ZonedDateTime.from('2025-01-20T15:30:00-05:00[America/New_York]');
+ * const result = addMilliseconds(zoned, 1500);
+ * // 2025-01-20T15:30:01.500-05:00[America/New_York]
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Negative values subtract milliseconds
+ * const instant = Temporal.Instant.from('2025-01-20T12:00:00.500Z');
+ * const result = addMilliseconds(instant, -250);
+ * // 2025-01-20T12:00:00.250Z[UTC] (250 milliseconds earlier)
+ * ```
+ */
+export declare function addMilliseconds(input: Temporal.Instant | Temporal.ZonedDateTime, milliseconds: number): Temporal.ZonedDateTime;
+//# sourceMappingURL=addMilliseconds.d.ts.map

package/dist/addMilliseconds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addMilliseconds.d.ts","sourceRoot":"","sources":["../src/addMilliseconds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,QAAQ,CAAC,OAAO,GAAG,QAAQ,CAAC,aAAa,EAChD,YAAY,EAAE,MAAM,GACnB,QAAQ,CAAC,aAAa,CAGxB"}

package/dist/addMilliseconds.js

@@ -0,0 +1,8 @@
+import {
+  addMilliseconds
+} from "./chunk-A5VVBYNT.js";
+import "./chunk-MJSZNWCV.js";
+export {
+  addMilliseconds
+};
+//# sourceMappingURL=addMilliseconds.js.map

package/dist/addMilliseconds.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/addMilliseconds.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=addMilliseconds.test.d.ts.map

package/dist/addMilliseconds.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addMilliseconds.test.d.ts","sourceRoot":"","sources":["../src/addMilliseconds.test.ts"],"names":[],"mappings":""}