### TZDateMini Example Usage

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Demonstrates basic usage of the TZDateMini class, including creating an instance, getting the timezone offset, and changing the timezone.

```typescript
import { TZDateMini } from "@date-fns/tz";

const date = new TZDateMini(2024, 2, 13, "Asia/Singapore");
const offset = date.getTimezoneOffset();
const newTz = date.withTimeZone("America/New_York");
```

--------------------------------

### Installation

Source: https://github.com/date-fns/tz/blob/main/README.md

Install the @date-fns/tz package using npm.

```bash
npm install @date-fns/tz --save
```

--------------------------------

### TZDate Constructor Examples

Source: https://github.com/date-fns/tz/blob/main/README.md

Examples of creating TZDate instances with different arguments, including time zone.

```javascript
new TZDate(2022, 2, "Asia/Singapore");

new TZDate(timestamp, "Asia/Singapore");

new TZDate("2024-09-12T00:00:00Z", "Asia/Singapore");
```

--------------------------------

### DST Transition Detection Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

An example of the output from tzScan() identifying a DST transition.

```typescript
{
  date: Date("2024-03-10T07:00:00.000Z"),  # When it happens
  change: 60,                               # Change in minutes
  offset: -240                              # New offset (UTC-4)
}
```

--------------------------------

### Example POSIX TZ String

Source: https://github.com/date-fns/tz/blob/main/tzdata/theory.html

A traditional POSIX TZ string example.

```plaintext
TZ="EST5EDT"
```

--------------------------------

### TZName Usage Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/types.md

Example demonstrating how to use the TZNameFormat type with the tzName function.

```typescript
import { tzName } from "@date-fns/tz";

function formatWithTimezone(date: Date, timeZone: string, format: TZNameFormat = "long"): string {
  const name = tzName(timeZone, date, format);
  return `${date.toISOString()} (${name})`;
}

console.log(formatWithTimezone(new Date(), "America/New_York", "short"));
//=> "2024-03-13T14:30:00Z (EDT)"

console.log(formatWithTimezone(new Date(), "America/New_York", "long"));
//=> "2024-03-13T14:30:00Z (Eastern Daylight Time)"
```

--------------------------------

### Format.js Polyfill Requirements

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Example of how to import Format.js polyfills for React Native and Hermes environments.

```typescript
import "@formatjs/intl-datetimeformat/polyfill";
import "@formatjs/intl-datetimeformat/locale-data/en";
import "@formatjs/intl-datetimeformat/add-golden-tz";
```

--------------------------------

### tzOffset Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzoffset.md

Demonstrates how tzOffset calculates timezone offsets and utilizes caching for performance.

```typescript
import {
  tzOffset
} from "@date-fns/tz";

const date = new Date();

// First call - creates Intl.DateTimeFormat, calculates offset
console.time("first");
const offset1 = tzOffset("America/New_York", date);
console.timeEnd("first"); // ~1-2ms

// Second call - reuses cached formatter
console.time("second");
const offset2 = tzOffset("America/New_York", date);
console.timeEnd("second"); // <1ms

console.log(offset1 === offset2); // true
```

--------------------------------

### Usage Example

Source: https://github.com/date-fns/tz/blob/main/README.md

Demonstrates how TZDate handles time zones and DST differences compared to the native Date object.

```typescript
import { TZDate } from "@date-fns/tz";
import { addHours } from "date-fns";

// Given that the system time zone is America/Los_Angeles
// where DST happens at Sunday, 13 March 2022, 02:00:00

// Using system time zone will produce 03:00 instead of 02:00 because of DST:
const date = new Date(2022, 2, 13);
addHours(date, 2).toString();
//=> 'Sun Mar 13 2022 03:00:00 GMT-0700 (Pacific Daylight Time)'

// Using Asia/Singapore will provide expected 02:00:
const tzDate = new TZDate(2022, 2, 13, "Asia/Singapore");
addHours(tzDate, 2).toString();
//=> 'Sun Mar 13 2022 02:00:00 GMT+0800 (Singapore Standard Time)'
```

--------------------------------

### DST Handling Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Demonstrates how date-fns-tz automatically handles DST transitions when calculating date intervals.

```typescript
import { TZDate } from "@date-fns/tz";
import { eachDayOfInterval } from "date-fns";

// March 10, 2024: DST begins in America/New_York
const days = eachDayOfInterval({
  start: new TZDate(2024, 2, 8, "America/New_York"),
  end: new TZDate(2024, 2, 12, "America/New_York"),
});

// All dates correctly calculated, skipping the DST gap
console.log(days.map(d => d.toString()));
```

--------------------------------

### TZChange Object Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/types.md

An example of the TZChange object structure returned by tzScan.

```typescript
{
  date: new Date("2024-03-10T07:00:00.000Z"),
  change: 60,           // Spring forward by 1 hour
  offset: -240          // New offset is UTC-4 (EDT)
}

// This means at 2024-03-10 07:00:00 UTC:
// - The local time in America/New_York jumped from 02:00 EST to 03:00 EDT
// - The offset changed from UTC-5 to UTC-4
```

--------------------------------

### Type Compatibility Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/types.md

Demonstrates that both TZDate and TZDateMini are valid Date instances and support timezone operations and date-fns functions.

```typescript
import { TZDate, TZDateMini } from "@date-fns/tz";

// Both are valid Date instances
const tzDate: Date = new TZDate(2024, 2, 13, "Asia/Singapore");
const mini: Date = new TZDateMini(2024, 2, 13, "Asia/Singapore");

// Both support timezone operations
console.log(tzDate.timeZone); // "Asia/Singapore"
console.log(mini.timeZone);   // "Asia/Singapore"

// Both work with date-fns
import { addDays } from "date-fns";
const result1 = addDays(tzDate, 1); // Returns TZDate
const result2 = addDays(mini, 1);   // Returns TZDateMini
```

--------------------------------

### Example Proleptic TZ String with DST Transition Time Range

Source: https://github.com/date-fns/tz/blob/main/tzdata/theory.html

An example of a proleptic TZ string demonstrating the extended DST transition time range allowed in POSIX.1-2024.

```plaintext
"<-02>2<-01>,M3.5.0/-1,M10.5.0/0"
```

--------------------------------

### Custom Implementation

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/constants.md

Example of how to implement the constructFromSymbol method in a custom date-like class to ensure compatibility with date-fns.

```typescript
class MyCustomDate {
  constructor(value, timezone) {
    this.value = value;
    this.timezone = timezone;
  }

  [Symbol.for("constructDateFrom")](date) {
    return new MyCustomDate(+new Date(date), this.timezone);
  }

  getTime() {
    return new Date(this.value).getTime();
  }

  toString() {
    return new Date(this.value).toString();
  }
}

// Now date-fns can work with MyCustomDate instances:
import { addDays } from "date-fns";

const customDate = new MyCustomDate(new Date(), "Asia/Singapore");
const nextDay = addDays(customDate, 1);
console.log(nextDay.timezone); // "Asia/Singapore"
```

--------------------------------

### Example Proleptic TZ String for New Zealand

Source: https://github.com/date-fns/tz/blob/main/tzdata/theory.html

An example of a proleptic TZ string for New Zealand after 2007, illustrating its complexity.

```plaintext
TZ='NZST-12NZDT,M9.5.0,M4.1.0/3'
```

--------------------------------

### UTC Offsets

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Examples of UTC Offsets accepted by the library.

```text
"+08:00"                # UTC+8 (colon format)
"-05:00"                # UTC-5
"+0800"                 # UTC+8 (no colon)
"-05"                   # UTC-5 (hour only)
```

--------------------------------

### IANA Time Zone Names

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Examples of IANA Time Zone Names accepted by the library.

```text
"America/New_York"      # Eastern Time
"Europe/London"         # UK Time
"Asia/Singapore"        # Singapore (no DST)
"Australia/Sydney"      # Australian Eastern Time
```

--------------------------------

### tzOffset function

Source: https://github.com/date-fns/tz/blob/main/README.md

Demonstrates getting the UTC offset in minutes for a given timezone and date.

```javascript
import { tzOffset } from "@date-fns/tz";

const date = new Date("2020-01-15T00:00:00Z");

tzOffset("Asia/Singapore", date);
//=> 480

tzOffset("America/New_York", date);
//=> -300

// Summer time:
tzOffset("America/New_York", "2020-01-15T00:00:00Z");
//=> -240
```

--------------------------------

### Creating Timezone-Aware Dates

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Examples of creating timezone-aware dates using the TZDate class with different construction methods.

```typescript
import { TZDate } from "@date-fns/tz";

// Multiple construction methods
const date1 = new TZDate(2024, 2, 13, "Asia/Singapore");
const date2 = new TZDate("2024-03-13T14:30:00Z", "America/New_York");
const date3 = TZDate.tz("Asia/Singapore", 2024, 2, 13);
const date4 = TZDate.tz("Asia/Singapore"); // Current time
```

--------------------------------

### Use "short" format

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzname.md

Example of using the 'short' format for timezone names, suitable for compact displays.

```typescript
tzName("America/Chicago", new Date(2024, 0, 1), "short")
//=> "CST"
```

--------------------------------

### Getting Timezone Information

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Examples of using tzOffset to get the UTC offset and tzName to get a human-readable timezone name.

```typescript
import { tzOffset, tzName } from "@date-fns/tz";

const date = new Date("2024-03-13T00:00:00Z");

// Get numeric offset
const offset = tzOffset("America/New_York", date);
console.log(offset); // -240 (UTC-4 during DST)

// Get readable name
const name = tzName("America/New_York", date, "long");
console.log(name); // "Eastern Daylight Time"
```

--------------------------------

### Creating TZDate Instances

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Demonstrates various ways to create TZDate instances using constructors and the static `tz` method.

```typescript
import { TZDate, TZDateMini } from "@date-fns/tz";

// Using constructors
const date1 = new TZDate(2024, 2, 13, "Asia/Singapore");
const date2 = new TZDate("2024-03-13T14:30:00Z", "America/New_York");
const date3 = new TZDate(1710332400000, "Europe/London");

// Using static tz method
const date4 = TZDate.tz("Asia/Singapore"); // current time
const date5 = TZDate.tz("Asia/Singapore", 2024, 2, 13);
```

--------------------------------

### Checking if a Timezone Exists

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzoffset.md

This example demonstrates how to check if a given timezone string is valid. It attempts to get the offset for the timezone; if the result is NaN, the timezone is considered invalid.

```typescript
import { tzOffset } from "@date-fns/tz";

function isValidTimeZone(timeZone) {
  try {
    const offset = tzOffset(timeZone, new Date());
    return !isNaN(offset);
  } catch {
    return false;
  }
}

console.log(isValidTimeZone("Asia/Singapore")); // true
console.log(isValidTimeZone("Invalid/Zone")); // false (returns NaN)
console.log(isValidTimeZone("+08:00")); // true
```

--------------------------------

### Detecting Offset Changes Over a Multi-Year Period

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzscan.md

This example shows how to identify all unique UTC offsets a timezone has used over a multi-year period. It uses `tzScan` to get all transitions and then extracts the unique offsets from these transitions, including the initial offset before the first change.

```typescript
import { tzScan } from "@date-fns/tz";

function getUniqueOffsetsInPeriod(timeZone, startYear, endYear) {
  const changes = tzScan(timeZone, {
    start: new Date(`${startYear}-01-01T00:00:00Z`),
    end: new Date(`${endYear}-12-31T23:59:59Z`),
  });
  
  // Get unique offsets from the changes, plus the initial offset
  const initialDate = new Date(`${startYear}-01-01T00:00:00Z`);
  const offsets = new Set();
  
  // Add initial offset (before first change)
  if (changes.length > 0) {
    // Get offset before first change
    const beforeDate = new Date(changes[0].date);
    beforeDate.setUTCHours(beforeDate.getUTCHours() - 1);
    const initialOffset = changes[0].offset - changes[0].change;
    offsets.add(initialOffset);
  }
  
  // Add all change offsets
  changes.forEach(c => offsets.add(c.offset));
  
  return Array.from(offsets).sort((a, b) => a - b);
}

const offsets = getUniqueOffsetsInPeriod("America/New_York", 2020, 2024);
console.log(offsets); // [-300, -240] (EST and EDT)
```

--------------------------------

### TZDate vs TZDateMini Formatting

Source: https://github.com/date-fns/tz/blob/main/README.md

Illustrates the difference in output between TZDateMini and TZDate when formatting.

```typescript
import { TZDateMini, TZDate } from "@date-fns/tz";

// TZDateMini will format date-time in the system time zone:
new TZDateMini(2022, 2, 13).toString();
//=> 'Sat Mar 12 2022 16:00:00 GMT-0800 (Pacific Standard Time)'

// TZDate will format date-time in the Singapore time zone, like expected:
new TZDate(2022, 2, 13).toString();
//=> 'Sun Mar 13 2022 00:00:00 GMT+0800 (Singapore Standard Time)'
```

--------------------------------

### TZChangeInterval Usage Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/types.md

Example demonstrating how to define and use TZChangeInterval for tzScan.

```typescript
import { tzScan, TZChangeInterval } from "@date-fns/tz";

const interval: TZChangeInterval = {
  start: new Date("2024-01-01T00:00:00Z"),
  end: new Date("2024-12-31T23:59:59Z"),
};

const changes = tzScan("America/New_York", interval);

// Helper function to create year-long intervals
function getYearInterval(year: number): TZChangeInterval {
  return {
    start: new Date(`${year}-01-01T00:00:00Z`),
    end: new Date(`${year}-12-31T23:59:59Z`),
  };
}

const ny2024Changes = tzScan("America/New_York", getYearInterval(2024));
```

--------------------------------

### TZChangeInterval Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzscan.md

Example of defining a TZChangeInterval for scanning timezone changes.

```typescript
import { tzScan } from "@date-fns/tz";

const interval: TZChangeInterval = {
  start: new Date("2024-01-01T00:00:00Z"),
  end: new Date("2024-12-31T23:59:59Z"),
};

const changes = tzScan("America/New_York", interval);
```

--------------------------------

### TZDate Constructor with Year, Month, Date

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Creates a new TZDate instance from year, month, and date.

```typescript
import { TZDate } from "@date-fns/tz";

const date = new TZDate(2024, 2, 13, "Asia/Singapore"); // March 13, 2024
```

--------------------------------

### TZDateMini Export

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Shows how to import TZDateMini from the mini date module.

```typescript
import { TZDateMini } from "@date-fns/tz/date/mini";
```

--------------------------------

### TZChange Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzscan.md

Example structure of a TZChange object representing a timezone offset change event.

```typescript
{
  date: Date("2024-03-10T07:00:00.000Z"),
  change: 60,           // Spring forward by 1 hour
  offset: -240          // New offset is UTC-4 (EDT)
}
```

--------------------------------

### TZDate Constructor with Year, Month, Date, Hours

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Creates a new TZDate instance from year, month, date, and hours.

```typescript
import { TZDate } from "@date-fns/tz";

const date = new TZDate(2024, 2, 13, 14, "Asia/Singapore");
```

--------------------------------

### Geographical TZ Example

Source: https://github.com/date-fns/tz/blob/main/tzdata/theory.html

An example of using a geographical TZ string, which is simpler than a proleptic one.

```plaintext
TZ='Pacific/Auckland'
```

--------------------------------

### TZDate Constructor with Year, Month, Date, Hours, Minutes

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Creates a new TZDate instance from year, month, date, hours, and minutes.

```typescript
import { TZDate } from "@date-fns/tz";

const date = new TZDate(2024, 2, 13, 14, 30, "America/New_York");
```

--------------------------------

### tzName function

Source: https://github.com/date-fns/tz/blob/main/README.md

Demonstrates getting the human-readable timezone name.

```javascript
import { tzName } from "@date-fns/tz";

tzName("Asia/Singapore", new Date("2020-01-01T00:00:00Z"));
//=> "Singapore Standard Time"
```

```javascript
import { tzName } from "@date-fns/tz";

const date = new Date("2020-01-01T00:00:00.000Z");

tzName("America/New_York", date, "short");
//=> "EST"

tzName("America/New_York", date, "shortGeneric");
//=> "ET"
```

--------------------------------

### Equivalent Ways to Access constructFromSymbol

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/constants.md

Shows different ways to access the constructFromSymbol, highlighting its global and consistent nature.

```typescript
// Direct import
import { constructFromSymbol } from "@date-fns/tz";

// Direct creation
Symbol.for("constructDateFrom")

// Used by date-fns internally
Symbol.for("constructDateFrom")

// All are equivalent:
Symbol.for("constructDateFrom") === Symbol.for("constructDateFrom") // true
constructFromSymbol === Symbol.for("constructDateFrom") // true
```

--------------------------------

### Converting between time zones

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Demonstrates how to create a TZDate object and convert it to a different time zone using the withTimeZone method.

```typescript
import { TZDate } from "@date-fns/tz";

const singapore = new TZDate(2024, 2, 13, 12, 0, "Asia/Singapore");
const newyork = singapore.withTimeZone("America/New_York");

console.log(singapore.toString());
//=> 'Sun Mar 13 2024 12:00:00 GMT+0800 (Singapore Standard Time)'

console.log(newyork.toString());
//=> 'Sat Mar 12 2024 23:00:00 GMT-0500 (Eastern Standard Time)'
```

--------------------------------

### TZDate.[Symbol.for("constructDateFrom")] method

Source: https://github.com/date-fns/tz/blob/main/README.md

Demonstrates constructing a Date instance in the same timezone as a TZDate instance.

```typescript
const sg = TZDate.tz("Asia/Singapore");

// Given that the system time zone is America/Los_Angeles

const date = sg[Symbol.for("constructDateFrom")](new Date(2024, 0, 1));

date.toString();
//=> 'Mon Jan 01 2024 16:00:00 GMT+0800 (Singapore Standard Time)'
```

```javascript
import { constructFromSymbol } from "@date-fns/tz";
```

--------------------------------

### Type Safety

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Showcases the full TypeScript support with comprehensive type definitions and usage examples.

```typescript
import {
  TZDate,
  TZDateMini,
  tzOffset,
  tzScan,
  tzName,
  tz,
  TZChange,
  TZChangeInterval,
  TZNameFormat,
  constructFromSymbol,
} from "@date-fns/tz";

const date: TZDate = new TZDate(2024, 2, 13, "Asia/Singapore");
const offset: number = tzOffset("Asia/Singapore", date);
const changes: TZChange[] = tzScan("America/New_York", {
  start: new Date(),
  end: new Date(),
});
const name: string = tzName("Europe/London", date, "long");
const context: (value: Date | number | string) => TZDate = tz("Asia/Singapore");
```

--------------------------------

### Using date-fns functions with TZDate

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Shows how to use standard date-fns functions like addDays with TZDate objects, preserving timezone information.

```typescript
import { TZDate } from "@date-fns/tz";
import { addDays, format } from "date-fns";

const date = new TZDate(2024, 2, 13, "Asia/Singapore");
const nextDay = addDays(date, 1);

console.log(nextDay.toString());
//=> 'Mon Mar 14 2024 00:00:00 GMT+0800 (Singapore Standard Time)'
```

--------------------------------

### Finding All Offsets in a Year

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzoffset.md

This example shows how to find all unique UTC offsets a timezone has within a given year. It iterates through each day of the year, calculates the offset, and stores unique offsets in a Set.

```typescript
import { tzOffset } from "@date-fns/tz";

function getAllOffsetsInYear(timeZone, year) {
  const offsets = new Set();
  
  // Check every day of the year
  for (let day = 0; day < 365; day++) {
    const date = new Date(year, 0, 1);
    date.setDate(date.getDate() + day);
    const offset = tzOffset(timeZone, date);
    offsets.add(offset);
  }
  
  return Array.from(offsets).sort((a, b) => a - b);
}

// America/New_York has two offsets: -300 (EST) and -240 (EDT)
console.log(getAllOffsetsInYear("America/New_York", 2024));
// [-300, -240]

// Asia/Singapore has one offset all year
console.log(getAllOffsetsInYear("Asia/Singapore", 2024));
// [480]
```

--------------------------------

### Using the Symbol Directly

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/constants.md

Shows how to use Symbol.for directly to achieve the same result as importing constructFromSymbol.

```typescript
import { TZDate } from "@date-fns/tz";

const tzDate = new TZDate(2024, 2, 13, "Asia/Singapore");

// Using Symbol.for directly
const result = tzDate[Symbol.for("constructDateFrom")](new Date(2024, 5, 15));
console.log(result.timeZone); // "Asia/Singapore"
```

--------------------------------

### toLocaleTimeString() Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Returns a locale-specific time string representation in the specified time zone.

```typescript
import { TZDate } from "@date-fns/tz";

const date = new TZDate(2024, 2, 13, 14, 30, "Asia/Singapore");
console.log(date.toLocaleTimeString("en-SG"));
//=> '14:30:00'
```

--------------------------------

### toLocaleDateString() Example

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Returns a locale-specific date string representation in the specified time zone.

```typescript
import { TZDate } from "@date-fns/tz";

const date = new TZDate(2024, 2, 13, "Asia/Singapore");
console.log(date.toLocaleDateString("en-SG"));
//=> '13/3/2024'
```

--------------------------------

### TZDate Constructor with Year, Month, Date, Hours, Minutes, Seconds

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Creates a new TZDate instance including seconds.

```typescript
import { TZDate } from "@date-fns/tz";

const date = new TZDate(2024, 2, 13, 14, 30, 45, "Europe/London");
```

--------------------------------

### TZDate Constructor with Year, Month, Date, Hours, Minutes, Seconds, Milliseconds

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Creates a new TZDate instance including milliseconds.

```typescript
import { TZDate } from "@date-fns/tz";

const date = new TZDate(2024, 2, 13, 14, 30, 45, 123, "Asia/Tokyo");
```

--------------------------------

### Sample Performance

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzscan.md

Demonstrates the performance of `tzScan` for different interval lengths, showing typical execution times.

```typescript
import { tzScan } from "@date-fns/tz";

console.time("Scan 2024");
const changes = tzScan("America/New_York", {
  start: new Date("2024-01-01T00:00:00Z"),
  end: new Date("2024-12-31T23:59:59Z"),
});
console.timeEnd("Scan 2024"); // ~1-5ms

console.time("Scan 2000-2030");
const longScan = tzScan("America/New_York", {
  start: new Date("2000-01-01T00:00:00Z"),
  end: new Date("2030-12-31T23:59:59Z"),
});
console.timeEnd("Scan 2000-2030"); // ~50-100ms
```

--------------------------------

### Example of invalid usage

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tz.md

Demonstrates how an invalid timezone name passed to tz() results in an invalid date.

```typescript
import { tz } from "@date-fns/tz";

const invalidContext = tz("Invalid/Timezone");
const result = new Date("2024-03-13");
const contextFn = invalidContext;
const tzDate = contextFn(result); // Creates TZDate with invalid state

console.log(tzDate.getTime()); // May be NaN
```

--------------------------------

### TZDate Constructor - Year and Month

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Creates a new TZDate instance from year and month, with day defaulting to 1.

```typescript
import { TZDate } from "@date-fns/tz";

const date = new TZDate(2024, 8, "America/Los_Angeles"); // Sept 1, 2024
```

--------------------------------

### TZDate Constructor - Default

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Creates a new TZDate instance in the system time zone with the current date and time.

```typescript
import { TZDate } from "@date-fns/tz";

const now = new TZDate();
```

--------------------------------

### Accepted Time Zone Formats

Source: https://github.com/date-fns/tz/blob/main/README.md

Examples of passing IANA time zone names or UTC offsets to the TZDate constructor.

```javascript
new TZDate(2022, 2, 13, "Asia/Singapore");

new TZDate(2022, 2, 13, "+08:00");

new TZDate(2022, 2, 13, "-2359");
```

--------------------------------

### Direct TZDate Usage with date-fns

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Example of using TZDate directly with date-fns functions, preserving timezone context.

```typescript
import { TZDate } from "@date-fns/tz";
import { tz } from "@date-fns/tz";
import { addDays, isSameMonth, format } from "date-fns";

// Direct TZDate usage
const tzDate = new TZDate(2024, 2, 13, "America/New_York");
const result = addDays(tzDate, 1); // Timezone preserved
console.log(result instanceof TZDate); // true

// Using tz() context
const context = tz("America/New_York");
const same = isSameMonth(date1, date2, { in: context });
```

--------------------------------

### TZDate Static Method tz()

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Creates a new TZDate instance in the given time zone with the current date and time.

```typescript
import { TZDate } from "@date-fns/tz";

// Create the current time in Singapore
const now = TZDate.tz("Asia/Singapore");
console.log(now.timeZone); // "Asia/Singapore"
```

--------------------------------

### TZDate Constructors

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Demonstrates the various ways to construct a TZDate object, mirroring native Date but with timezone support.

```typescript
new TZDate()                              # System timezone, now
new TZDate(timestamp)                     # System timezone, timestamp
new TZDate(dateString)                    # System timezone, string
new TZDate(year, month)                   # System timezone, Y/M
new TZDate(year, month, date)             # System timezone, Y/M/D
new TZDate(year, month, date, hours, ...) # System timezone, full datetime
new TZDate(..., "Asia/Singapore")         # Any variant + timezone
```

--------------------------------

### TZDate Constructor - Date String

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzdate.md

Creates a new TZDate instance from a date/time string and optional time zone.

```typescript
import { TZDate } from "@date-fns/tz";

const date1 = new TZDate("2024-09-12T15:30:00Z", "Asia/Singapore");
const date2 = new TZDate("2024-09-12");
```

--------------------------------

### Working with date-fns v4+

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Demonstrates how to use TZDate instances with date-fns v4+ functions, preserving timezone context.

```typescript
import { TZDate } from "@date-fns/tz";
import { tz } from "@date-fns/tz";
import { addDays, isSameDay } from "date-fns";

// Using TZDate directly
const tzDate = new TZDate(2024, 2, 13, "Asia/Singapore");
const nextDay = addDays(tzDate, 1); // Timezone preserved
console.log(nextDay.timeZone); // "Asia/Singapore"

// Using tz() context function
const context = tz("America/New_York");
const result = isSameDay(date1, date2, { in: context });
```

--------------------------------

### Import Paths

Source: https://github.com/date-fns/tz/blob/main/_autodocs/README.md

Illustrates different ways to import APIs from the @date-fns/tz package, including main exports and specific imports.

```typescript
// Main export - all APIs
import { TZDate, tzOffset, tzScan, tzName, tz } from "@date-fns/tz";

// Specific imports
import { TZDate } from "@date-fns/tz/date";
import { TZDateMini } from "@date-fns/tz/date/mini";
import { tzOffset } from "@date-fns/tz/tzOffset";
import { tzScan } from "@date-fns/tz/tzScan";
import { tzName } from "@date-fns/tz/tzName";
import { tz } from "@date-fns/tz/tz";
import { constructFromSymbol } from "@date-fns/tz/constants";
```

--------------------------------

### Scanning Multiple Years

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tzscan.md

Usage example for scanning timezone changes across multiple years for a given timezone.

```typescript
import { tzScan } from "@date-fns/tz";

const changes = tzScan("Europe/London", {
  start: new Date("2020-01-01T00:00:00Z"),
  end: new Date("2024-12-31T23:59:59Z"),
});

// London has 2 transitions per year (spring forward, fall back)
console.log(changes.length); // 10 (5 years × 2 transitions)

changes.forEach(change => {
  console.log(`${change.date.toISOString()}: ${change.change > 0 ? 'Spring forward' : 'Fall back'} (${change.change} min, new offset ${change.offset})`);
});
```

--------------------------------

### Checking your date-fns version

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tz.md

Code snippet to verify that the installed date-fns version is 4.0.0 or higher, which is a requirement for using the 'in' option.

```typescript
import { version } from "date-fns";
console.log(version); // Must be "4.0.0" or higher
```

--------------------------------

### Basic Usage with date-fns Functions

Source: https://github.com/date-fns/tz/blob/main/_autodocs/api-reference/tz.md

Demonstrates how to use the `tz` function to create a timezone context and apply it to `isSameDay` and `addDays` from date-fns.

```typescript
import { tz } from "@date-fns/tz";
import { isSameDay, addDays, format } from "date-fns";

const singaporeContext = tz("Asia/Singapore");

// Use with isSameDay
const result = isSameDay("2024-09-09T23:00:00-04:00", "2024-09-10T10:00:00+08:00", {
  in: singaporeContext,
});
console.log(result); // true - they're the same day in Singapore time

// Use with addDays
const date = new Date("2024-03-13T10:00:00Z");
const nextDay = addDays(date, 1, { in: singaporeContext });
console.log(nextDay.toString()); 
//=> '2024-03-14T10:00:00+08:00' in Singapore timezone
```