# @multisystemsuite/timezone-engine-core

Core timezone engine — detection, conversion, formatting, world clock, and site utilities. Framework-agnostic (works in Node.js, browser, SSR).

## What it is used for

- Timezone detection (browser, Node, server)
- UTC ↔ timezone conversion and DST checks
- Locale-aware date formatting (ISO, SHORT, LONG, regional)
- World clock and timezone comparison
- **Site utilities** — normalise UI values like `"America/New_York (GMT-5:00)"` before IANA APIs
- Enterprise engine with plugins, cache, and config

## Install

```bash
npm install @multisystemsuite/timezone-engine-core
```

## Usage

```typescript
import {
  detectTimezone,
  convertTimezone,
  formatDate,
  getWorldClock,
  compareTimezones,
  normalizeTimezone,
  safeTimezone,
  formatDateForSite,
  validateTimezone,
  safeTimezoneFallback,
  ensureUTCStorage,
  timezoneSafeCompare,
  detectClockDrift,
  syncServerTime,
} from "@multisystemsuite/timezone-engine-core";

normalizeTimezone("Asia/Kolkata (GMT+5:30)"); // "Asia/Kolkata"

formatDate(new Date(), { format: "FULL", timezone: "Asia/Kolkata" });

convertTimezone({
  sourceTimezone: "UTC",
  targetTimezone: "America/New_York",
  date: new Date(),
});
```

## Site / microservice drop-in module

For admin-service, qc-service, shopfloor-service:

```typescript
import {
  normalizeTimezone,
  sanitizeTimezoneForDB,
  formatDateForSite,
} from "@multisystemsuite/timezone-engine-core/site";
```

## Subpath exports

| Import path      | Contents                                             |
| ---------------- | ---------------------------------------------------- |
| `/detection`     | `detectTimezone`, `isValidTimezone`                  |
| `/conversion`    | `toUTC`, `fromUTC`, `convertTimezone`                |
| `/formatting`    | `formatDate`, `formatRelativeTime`                   |
| `/world-clock`   | `getWorldClock`, `createLiveClockUpdater`            |
| `/comparison`    | `compareTimezones`, `findCommonWorkingHours`         |
| `/normalization` | `normalizeTimezone`, `safeTimezone`                  |
| `/site`          | Site formatting + token-based `formatDate`           |
| `/validation`    | Via main: `validateTimezone`, `safeTimezoneFallback` |
| `/storage`       | Via main: `ensureUTCStorage`, `parseUTCStorage`      |

### Validation & UTC storage

```typescript
import {
  validateTimezone,
  aliasTimezoneResolver,
  ensureUTCStorage,
  timezoneSafeCompare,
  syncServerTime,
} from "@multisystemsuite/timezone-engine-core";

validateTimezone("IST"); // false
ensureUTCStorage(new Date(), "Asia/Kolkata");
syncServerTime({ clientTimezone: "Asia/Kolkata" });
```

## Related packages

- `@multisystemsuite/timezone-engine-world-data` — offline IANA/country metadata
- `@multisystemsuite/timezone-engine-utils` — cache and plugins
- `@multisystemsuite/timezone-engine-shared-types` — TypeScript types

## Keywords

`timezone`, `utc`, `conversion`, `formatting`, `world-clock`, `iana`, `dst`, `typescript`, `enterprise`, `date-fns`, `ssr`

## License

MIT