### Install zod-timezone-validation

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

Install the package using npm or yarn. Zod v4+ is a peer dependency.

```bash
npm install zod-timezone-validation
```

```bash
yarn add zod-timezone-validation
```

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

### Create Timezone Schemas

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

Import and use the createTimezoneSchemas factory function to get schema instances. This allows for isolated schema configurations.

```typescript
import { createTimezoneSchemas } from 'zod-timezone-validation';

const {
  CoercedCanonicalTimezoneSchema,
  CanonicalTimezoneSchema,
  TimezoneSchema,
} = createTimezoneSchemas();
```

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

### Default Canonical Mode (Strict IANA)

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

By default, createTimezoneSchemas uses strict IANA canonical names for consistent cross-environment behavior. This example shows how 'Asia/Calcutta' is coerced to 'Asia/Kolkata'.

```typescript
import { createTimezoneSchemas } from 'zod-timezone-validation';

// Default: strict IANA canonical names (consistent across environments)
const { CoercedCanonicalTimezoneSchema } = createTimezoneSchemas();

// Asia/Calcutta will always become Asia/Kolkata, regardless of the runtime
const result = CoercedCanonicalTimezoneSchema.parse('Asia/Calcutta');
console.log(result); // => 'Asia/Kolkata'
```

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

### Get Supported Timezones with Intl API

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

Retrieve an array of all IANA timezone names supported by the current runtime environment. This is useful for populating dropdowns or validating user input against available options.

```typescript
const availableTimezones = Intl.supportedValuesOf('timeZone');

console.log(availableTimezones);
// => ['Africa/Abidjan', 'Africa/Accra', 'Africa/Addis_Ababa', ..., 'Zulu']
```

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

### Combining Canonical Mode and Custom Mappings

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

Demonstrates creating schemas with both runtime canonical mode and custom timezone mappings.

```typescript
import { createTimezoneSchemas } from 'zod-timezone-validation';

const { CoercedCanonicalTimezoneSchema, CanonicalTimezoneSchema } = createTimezoneSchemas({
  canonicalMode: 'runtime',
  customMappings: [
    ['legacy/internal', 'America/Chicago'],
  ],
});
```

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

### Migration to v2: Factory Function Pattern

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

Illustrates the shift from global mutable schemas in v1.x to a factory function pattern in v2 for creating timezone schemas. This change promotes better isolation and configuration.

```typescript
// Before (v1.x)
import {
  CoercedCanonicalTimezoneSchema,
  CanonicalTimezoneSchema,
  TimezoneSchema,
  configureTimezoneSchema,
} from 'zod-timezone-validation';

configureTimezoneSchema({ canonicalMode: 'iana' });
CoercedCanonicalTimezoneSchema.parse('Asia/Calcutta');
```

```typescript
// After (v2)
import { createTimezoneSchemas } from 'zod-timezone-validation';

const { CoercedCanonicalTimezoneSchema } = createTimezoneSchemas();
CoercedCanonicalTimezoneSchema.parse('Asia/Calcutta');
```

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

### Runtime Canonical Mode

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

Opt into the runtime's Intl implementation for canonical mode. Note that results may vary between environments.

```typescript
import { createTimezoneSchemas } from 'zod-timezone-validation';

// Opt into runtime's Intl implementation (may vary by environment)
const { CoercedCanonicalTimezoneSchema: RuntimeSchema } = createTimezoneSchemas({
  canonicalMode: 'runtime',
});
```

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

### Custom Timezone Mappings

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

Provide custom timezone mappings to override built-in behavior. Mappings are case-insensitive and take precedence over IANA and runtime mappings.

```typescript
import { createTimezoneSchemas } from 'zod-timezone-validation';

const { CoercedCanonicalTimezoneSchema } = createTimezoneSchemas({
  // case-insensitive keys and values
  customMappings: [
    // Force a specific mapping
    ['Asia/Calcutta', 'Asia/Kolkata'],
    // Add a custom alias
    ['my/customzone', 'America/New_York'],
    // Introduce a new timezone name (will be assumed valid and canonical)
    ['legacy/zone', 'My/New/Canonical'],
  ],
});

const result1 = CoercedCanonicalTimezoneSchema.parse('My/CustomZone');
console.log(result1); // => 'America/New_York'

const result2 = CoercedCanonicalTimezoneSchema.parse('Legacy/Zone');
console.log(result2); // => 'My/New/Canonical'
```

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

### Lenient Timezone Validation

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

Use TimezoneSchema for lenient validation, accepting both canonical and non-canonical IANA timezone names without transformation. Throws an error for invalid timezones.

```typescript
import { createTimezoneSchemas } from 'zod-timezone-validation';

const { TimezoneSchema } = createTimezoneSchemas();

// Accepts canonical names
const result1 = TimezoneSchema.parse('Australia/Sydney');
console.log(result1); // => 'Australia/Sydney'

// Also accepts non-canonical names
const result2 = TimezoneSchema.parse('US/Eastern');
console.log(result2); // => 'US/Eastern'

// Throws an error for invalid timezones
try {
  TimezoneSchema.parse('Mars/Olympus_Mons');
} catch (e) {
  console.error(e); // ZodError
}
```

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

### Strict Canonical Timezone Validation

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

Use CanonicalTimezoneSchema to ensure a string is a strictly canonical IANA timezone name. It rejects valid but non-canonical names.

```typescript
import { createTimezoneSchemas } from 'zod-timezone-validation';

const { CanonicalTimezoneSchema } = createTimezoneSchemas();

// Accepts canonical names
const result = CanonicalTimezoneSchema.parse('Europe/London');
console.log(result); // => 'Europe/London'

// Rejects non-canonical names
try {
  CanonicalTimezoneSchema.parse('GB'); // 'GB' is a non-canonical alias for 'Europe/London'
} catch (e) {
  console.error(e); // ZodError
}
```

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

### CoercedCanonicalTimezoneSchema Usage

Source: https://github.com/roman86/zod-timezone-validation/blob/main/README.md

This schema validates and transforms non-canonical timezone names to their canonical form. It accepts canonical names as is and throws errors for invalid timezones.

```typescript
import { createTimezoneSchemas } from 'zod-timezone-validation';

const { CoercedCanonicalTimezoneSchema } = createTimezoneSchemas();

// Transforms non-canonical to canonical
const result1 = CoercedCanonicalTimezoneSchema.parse('Asia/Calcutta');
console.log(result1); // => 'Asia/Kolkata'

// Keeps canonical names as they are
const result2 = CoercedCanonicalTimezoneSchema.parse('America/New_York');
console.log(result2); // => 'America/New_York'

// Throws an error for invalid timezones
try {
  CoercedCanonicalTimezoneSchema.parse('Invalid/Timezone');
} catch (e) {
  console.error(e); // ZodError
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.