@lbd-sh/date-tz 1.0.6 → 1.0.8

package/README.md

@@ -1,25 +1,48 @@
-# Date TZ
+# Date TZ ⏰✨
 
-Powerful, dependency-free timezone utilities for JavaScript and TypeScript. `DateTz` keeps minute-precision timestamps aligned with IANA timezones, detects daylight-saving transitions automatically, and pairs a tiny API with comprehensive TypeScript definitions.
+`DateTz` is the timezone swiss‑army knife for modern JavaScript and TypeScript projects. It keeps minute-precision timestamps aligned with IANA zones, gracefully glides across daylight-saving transitions, and exposes a lightweight API that feels familiar yet powerful. Whether you are building dashboards, schedulers, or automation pipelines, DateTz keeps your time math honest. 🌍
 
-## TL;DR
+---
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Installation](#installation)
+3. [Why DateTz?](#why-datetz)
+4. [API Surface Overview](#api-surface-overview)
+5. [Formatting Tokens](#formatting-tokens)
+6. [Core Concepts & Recipes](#core-concepts--recipes)
+7. [Daylight Saving Time Deep Dive](#daylight-saving-time-deep-dive)
+8. [Real-World Playbook](#real-world-playbook)
+9. [Build & Distribution](#build--distribution)
+10. [TypeScript & Tooling](#typescript--tooling)
+11. [Performance Tips](#performance-tips)
+12. [FAQ & Troubleshooting](#faq--troubleshooting)
+13. [Contributing](#contributing)
+14. [License](#license)
+
+---
+
+## Quick Start
 
 ```ts
 import { DateTz } from '@lbd-sh/date-tz';
 
+// Create a meeting in Rome and preview it elsewhere
 const rome = new DateTz(Date.UTC(2025, 5, 15, 7, 30), 'Europe/Rome');
+const nyc = rome.cloneToTimezone('America/New_York');
 
 rome.toString();                              // "2025-06-15 09:30:00"
 rome.toString('DD LM YYYY HH:mm tz', 'en');   // "15 June 2025 09:30 Europe/Rome"
-rome.isDst;                                   // true
-
-const nyc = rome.cloneToTimezone('America/New_York');
 nyc.toString('YYYY-MM-DD HH:mm tz');          // "2025-06-15 03:30 America/New_York"
 
-rome.add(2, 'day').set(11, 'hour');
-rome.toString('YYYY-MM-DD HH:mm');            // "2025-06-17 11:30"
+rome.add(2, 'day').set(11, 'hour');           // Mutating, still DST-safe
 ```
 
+Need a full workflow? Jump to the [Real-World Playbook](#real-world-playbook). 👇
+
+---
+
 ## Installation
 
 ```bash
@@ -30,31 +53,41 @@ yarn add @lbd-sh/date-tz
 pnpm add @lbd-sh/date-tz
 ```
 
+DateTz ships as CommonJS with TypeScript declarations. No runtime dependencies, no polyfills.
+
+---
+
 ## Why DateTz?
 
-- **Predictable arithmetic** – timestamps are truncated to minutes to avoid millisecond drift.
-- **DST aware** – offsets come from the bundled `timezones` map and are verified via `Intl.DateTimeFormat` when available.
-- **Rich formatting/parsing** – reuse familiar tokens (`YYYY`, `MM`, `hh`, `AA`, `tz`, `LM` for locale month names, and more).
-- **Lean footprint** – no runtime dependencies, CommonJS output plus type declarations.
-- **Ergonomic conversions** – move or clone dates across timezones in one call.
+- **Predictable math** 🧮 – timestamps are truncated to minutes so cron-like workflows never drift by milliseconds.
+- **DST aware** 🌓 – offsets are sourced from the bundled `timezones` map and double-checked via `Intl.DateTimeFormat`.
+- **Expressive formatting** 🖨️ – familiar tokens (`YYYY`, `MM`, `hh`, `AA`, `tz`, `LM`, etc.) with locale-aware month names.
+- **Simple conversions** 🔁 – `convertToTimezone` and `cloneToTimezone` make cross-zone comparisons painless.
+- **TypeScript-first** 📘 – strong typings, `IDateTz` contract, and declaration files baked in.
+- **Zero dependencies** 🪶 – keep bundles lean while gaining runtime confidence.
 
-## API Surface at a Glance
+---
+
+## API Surface Overview
 
 | Member | Description |
 | ------ | ----------- |
-| `new DateTz(value, tz?)` | Accepts a timestamp or an `IDateTz` compliant object plus an optional timezone id. |
-| `DateTz.now(tz?)` | Returns the current moment in the given timezone (default `UTC`). |
-| `DateTz.parse(string, pattern?, tz?)` | Creates a date from a formatted string. |
-| `DateTz.defaultFormat` | Global default pattern used by `toString()` with no args. |
-| Instance getters | `year`, `month`, `day`, `hour`, `minute`, `dayOfWeek`, `isDst`, `timezoneOffset`. |
-| Instance methods | `toString(pattern?, locale?)`, `compare(other)`, `isComparable(other)`, `add(value, unit)`, `set(value, unit)`, `convertToTimezone(tz)`, `cloneToTimezone(tz)`. |
+| `new DateTz(value, tz?)` | Build from a timestamp or an `IDateTz`-compatible object (timezone defaults to `UTC`). |
+| `DateTz.now(tz?)` | Current moment in the requested timezone. |
+| `DateTz.parse(str, pattern?, tz?)` | Parse formatted strings into `DateTz` instances. |
+| `DateTz.defaultFormat` | Default pattern used by `toString()` when no arguments are provided. |
+| Getters | `year`, `month`, `day`, `hour`, `minute`, `dayOfWeek`, `isDst`, `timezoneOffset`. |
+| Mutators | `add(value, unit)`, `set(value, unit)`, `convertToTimezone(tz)` (mutating), `cloneToTimezone(tz)` (immutable). |
+| Comparison | `compare(other)`, `isComparable(other)` guard against cross-zone mistakes. |
+
+---
 
-## Pattern Tokens
+## Formatting Tokens
 
 | Token | Meaning | Example |
 | ----- | ------- | ------- |
-| `YYYY`, `yyyy` | Four digit year | `2025` |
-| `YY`, `yy` | Two digit year | `25` |
+| `YYYY`, `yyyy` | Four-digit year | `2025` |
+| `YY`, `yy` | Two-digit year | `25` |
 | `MM` | Month (01–12) | `06` |
 | `LM` | Locale month name (capitalised) | `June` |
 | `DD` | Day of month (01–31) | `15` |
@@ -62,251 +95,260 @@ pnpm add @lbd-sh/date-tz
 | `hh` | Hour (01–12) | `03` |
 | `mm` | Minute (00–59) | `30` |
 | `ss` | Second (00–59) | `00` |
-| `aa` | `am`/`pm` marker | `am` |
-| `AA` | `AM`/`PM` marker | `PM` |
+| `aa` | Lowercase am/pm marker | `pm` |
+| `AA` | Uppercase AM/PM marker | `PM` |
 | `tz` | Timezone identifier | `Europe/Rome` |
 
-> Need literal text? Keep it inside square brackets. Example: `YYYY-MM-DD[ @ ]HH:mm` → `2025-06-15 @ 09:30`. Characters inside brackets remain unchanged.
+> Literal text? Wrap it in square brackets: `YYYY-MM-DD[ @ ]HH:mm` → `2025-06-15 @ 09:30`.
 
-## Creating Dates
+---
 
-```ts
-import { DateTz, IDateTz } from '@lbd-sh/date-tz';
+## Core Concepts & Recipes
 
-// From a unix timestamp (milliseconds)
-const utcMeeting = new DateTz(Date.UTC(2025, 0, 1, 12, 0), 'UTC');
+### Creating Dates
 
-// From another DateTz-like object
-const seed: IDateTz = { timestamp: Date.now(), timezone: 'Asia/Tokyo' };
-const tokyo = new DateTz(seed);
+```ts
+import { DateTz, IDateTz } from '@lbd-sh/date-tz';
 
-// Using the helper
-const laNow = DateTz.now('America/Los_Angeles');
+const utc = new DateTz(Date.now(), 'UTC');
+const tokyo = new DateTz({ timestamp: Date.now(), timezone: 'Asia/Tokyo' } satisfies IDateTz);
+const la = DateTz.now('America/Los_Angeles');
 ```
 
-### Working With Plain Date Objects
+### From Native Date
 
 ```ts
 const native = new Date();
 const madrid = new DateTz(native.getTime(), 'Europe/Madrid');
-
-// Alternatively, keep everything UTC and convert when needed
-const fromUtc = new DateTz(native.getTime(), 'UTC').cloneToTimezone('Europe/Madrid');
+const alwaysUtc = new DateTz(native.getTime(), 'UTC').cloneToTimezone('Europe/Madrid');
 ```
 
-## Formatting Showcases
+### Formatting Showcases
 
 ```ts
-const order = new DateTz(Date.UTC(2025, 10, 5, 16, 45), 'Europe/Paris');
+const invoice = new DateTz(Date.UTC(2025, 10, 5, 16, 45), 'Europe/Paris');
 
-order.toString();                             // "2025-11-05 17:45:00"
-order.toString('DD/MM/YYYY HH:mm');           // "05/11/2025 17:45"
-order.toString('LM DD, YYYY hh:mm aa', 'fr'); // "Novembre 05, 2025 05:45 pm"
-order.toString('[Order timezone:] tz');       // "Order timezone: Europe/Paris"
+invoice.toString();                                 // "2025-11-05 17:45:00"
+invoice.toString('DD/MM/YYYY HH:mm');               // "05/11/2025 17:45"
+invoice.toString('LM DD, YYYY hh:mm aa', 'fr');     // "Novembre 05, 2025 05:45 pm"
+invoice.toString('[Order timezone:] tz');           // "Order timezone: Europe/Paris"
 ```
 
-### Locale-sensitive Month Names
-
-`LM` maps to `new Date(year, month, 3).toLocaleString(locale, { month: 'long' })` ensuring accurate localisation without full `Intl` formatting.
-
-## Parsing Scenarios
+### Parsing Scenarios
 
 ```ts
-// Standard 24h format
-const release = DateTz.parse('2025-09-01 02:30', 'YYYY-MM-DD HH:mm', 'Asia/Singapore');
-
-// 12h format (requires AM/PM marker)
-const dinner = DateTz.parse('03-18-2025 07:15 PM', 'MM-DD-YYYY hh:mm AA', 'America/New_York');
-
-// Custom tokens with literal text
-const promo = DateTz.parse('Sale closes 2025/03/31 @ 23:59', 'Sale closes YYYY/MM/DD [@] HH:mm', 'UTC');
+DateTz.parse('2025-09-01 02:30', 'YYYY-MM-DD HH:mm', 'Asia/Singapore'); // 24h format
+DateTz.parse('03-18-2025 07:15 PM', 'MM-DD-YYYY hh:mm AA', 'America/New_York'); // 12h
+DateTz.parse('Sale closes 2025/03/31 @ 23:59', 'Sale closes YYYY/MM/DD [@] HH:mm', 'UTC'); // Literals
 ```
 
-Parsing throws when the timezone id is missing or invalid, or when pattern/token combos are incompatible (for example `hh` without `aa`/`AA`).
+Parsing throws on invalid zones or incompatible patterns (e.g. `hh` without `aa`/`AA`).
 
-## Arithmetic Cookbook
+### Arithmetic Cookbook
 
 ```ts
 const sprint = new DateTz(Date.UTC(2025, 1, 1, 9, 0), 'Europe/Amsterdam');
 
-sprint.add(2, 'week'); // ❌ week not supported
-// Use compositions instead:
-sprint.add(14, 'day');
-
-// Move to first business day of next month
-sprint.set(sprint.month + 1, 'month');
-sprint.set(1, 'day');
-while ([0, 6].includes(sprint.dayOfWeek)) {
-  sprint.add(1, 'day');
-}
-
-// Shift to 10:00 local time
-sprint.set(10, 'hour').set(0, 'minute');
+sprint.add(14, 'day'); // Compose to simulate weeks
+sprint.set(sprint.month + 1, 'month').set(1, 'day'); // First day of next month
+while ([0, 6].includes(sprint.dayOfWeek)) sprint.add(1, 'day'); // Skip weekend
+sprint.set(10, 'hour').set(0, 'minute'); // Move to 10:00
 ```
 
-`add` accepts `minute`, `hour`, `day`, `month`, `year`. Compose multiple calls for complex adjustments. Overflows and leap years are handled automatically.
-
-### Immutable Patterns
-
-`add`, `set`, and `convertToTimezone` mutate the instance. Use `cloneToTimezone` or spread semantics when immutability is preferred:
+### Immutability Pattern
 
 ```ts
 const base = DateTz.now('UTC');
-const iteration = new DateTz(base);
-iteration.add(1, 'day');
+const nextRun = new DateTz(base).add(1, 'day');
 ```
 
-## Comparing & Sorting
+Mutators change the instance; use cloning when you need persistence.
+
+### Comparing & Sorting
 
 ```ts
 const slots = [
-  new DateTz(Date.UTC(2025, 6, 10, 8, 0), 'Europe/Rome'),
-  new DateTz(Date.UTC(2025, 6, 10, 9, 0), 'Europe/Rome'),
-  new DateTz(Date.UTC(2025, 6, 9, 18, 0), 'Europe/Rome'),
+  DateTz.parse('2025-06-15 08:00', 'YYYY-MM-DD HH:mm', 'Europe/Rome'),
+  DateTz.parse('2025-06-15 09:00', 'YYYY-MM-DD HH:mm', 'Europe/Rome'),
+  DateTz.parse('2025-06-14 18:00', 'YYYY-MM-DD HH:mm', 'Europe/Rome'),
 ];
 
 slots.sort((a, b) => a.compare(b));
 ```
 
-`compare` throws if timezones differ:
+Always guard cross-zone comparisons:
 
 ```ts
 const rome = DateTz.now('Europe/Rome');
 const ny = DateTz.now('America/New_York');
 
-if (!rome.isComparable(ny)) {
-  ny.convertToTimezone(rome.timezone);
-}
+if (!rome.isComparable(ny)) ny.convertToTimezone(rome.timezone);
+```
+
+---
+
+## Daylight Saving Time Deep Dive
+
+```ts
+const dstEdge = new DateTz(Date.UTC(2025, 2, 30, 0, 30), 'Europe/Rome'); // DST start night
 
-rome.compare(ny);
+dstEdge.toString();        // "2025-03-30 01:30:00"
+dstEdge.add(1, 'hour');
+dstEdge.toString();        // "2025-03-30 03:30:00" (skips 02:30)
+dstEdge.isDst;             // true
 ```
 
-## Timezone Conversion Deep Dive
+Under the hood:
+
+- Offsets are cached per timestamp (`offsetCache`) for speed.
+- If `Intl.DateTimeFormat` is available, DateTz validates the actual offset at runtime.
+- Without `Intl`, DateTz falls back to the static `timezones` map, so you can safely run on serverless or sandboxed environments.
+
+### Timezone Conversion
 
 ```ts
 const flight = new DateTz(Date.UTC(2025, 3, 28, 20, 0), 'Europe/London');
 
-const takeoff = flight.cloneToTimezone('America/Los_Angeles');
+const takeoff = flight.cloneToTimezone('America/Los_Angeles'); // immutable
 const landing = flight.cloneToTimezone('Asia/Tokyo');
-
-takeoff.isDst; // false (London DST might not have started yet)
-landing.isDst; // true or false depending on Tokyo rules
 ```
 
-- `convertToTimezone` mutates the instance.
-- `cloneToTimezone` returns a new instance.
-- Both refresh the cached offset and leverage the `Intl` API to detect real-world DST offsets (falling back to the static map).
+Use `convertToTimezone` if you want to mutate the instance in-place.
 
-### DST Transition Example
+---
+
+## Real-World Playbook
+
+### Scheduling Emails Across Offices 📧
 
 ```ts
-const dstEdge = new DateTz(Date.UTC(2025, 2, 30, 0, 30), 'Europe/Rome'); // Night DST starts
+const offices = [
+  { tz: 'Europe/Rome', hour: 9 },
+  { tz: 'America/New_York', hour: 9 },
+  { tz: 'Asia/Tokyo', hour: 9 },
+];
 
-dstEdge.toString();          // "2025-03-30 01:30:00"
-dstEdge.add(1, 'hour');
-dstEdge.toString();          // "2025-03-30 03:30:00" (skips 02:30 automatically)
-dstEdge.isDst;               // true
+const base = DateTz.now('UTC').set(0, 'minute');
+
+const sends = offices.map(({ tz, hour }) => {
+  const local = new DateTz(base).convertToTimezone(tz);
+  local.set(hour, 'hour');
+  if (local.compare(base) < 0) local.add(1, 'day');
+  return local;
+});
 ```
 
-## Working with Collections
+### React Component Integration ⚛️
 
-```ts
-const timeline = [
-  DateTz.parse('2025-06-15 09:30', 'YYYY-MM-DD HH:mm', 'Europe/Rome'),
-  DateTz.parse('2025-06-15 10:00', 'YYYY-MM-DD HH:mm', 'Europe/Rome'),
-  DateTz.parse('2025-06-15 09:45', 'YYYY-MM-DD HH:mm', 'Europe/Rome'),
-];
+```tsx
+import { useMemo } from 'react';
+import { DateTz } from '@lbd-sh/date-tz';
 
-const sorted = timeline.slice().sort((a, b) => a.compare(b));
+export function Countdown({ timestamp, tz }: { timestamp: number; tz: string }) {
+  const target = useMemo(() => new DateTz(timestamp, tz), [timestamp, tz]);
+  return (
+    <span title={target.toString('YYYY-MM-DD HH:mm tz')}>
+      {target.toString('DD MMM YYYY, HH:mm', navigator.language)}
+    </span>
+  );
+}
+```
 
-// Group by day
-const byDate = sorted.reduce<Record<string, DateTz[]>>((acc, slot) => {
-  const key = slot.toString('YYYY-MM-DD');
-  (acc[key] ||= []).push(slot);
-  return acc;
-}, {});
+### Express Middleware 🛤️
+
+```ts
+app.use((req, _res, next) => {
+  const headerTz = req.header('x-user-tz') ?? 'UTC';
+  req.context = {
+    now: () => DateTz.now(headerTz),
+  };
+  next();
+});
 ```
 
-## Serialization Tips
+### Testing Automation with Jest 🧪
 
 ```ts
-const payload = {
-  createdAt: DateTz.now('UTC').toString(),
-  timestamp: Date.now(),
-};
+import { DateTz } from '@lbd-sh/date-tz';
 
-// Later...
-const restored = new DateTz(payload.timestamp, 'UTC');
+describe('billing cutoff', () => {
+  it('moves to next business day when on weekend', () => {
+    const friday = DateTz.parse('2025-06-13 17:00', 'YYYY-MM-DD HH:mm', 'Europe/Rome');
+    friday.add(1, 'day');
+    expect(friday.dayOfWeek).toBe(6);
+    friday.add(2, 'day');
+    expect(friday.dayOfWeek).toBe(1);
+  });
+});
 ```
 
-Prefer storing the timestamp (UTC) and timezone id. When deserialising, feed both back into the constructor for deterministic results.
+---
 
-## Extending the Timezone Map
+## Build & Distribution
 
-```ts
-import { timezones } from '@lbd-sh/date-tz';
+- The compiled CommonJS bundle plus declarations live in `dist/` (`index.js`, `index.d.ts`, maps, and helpers).
+- `package.json` already points `main` and `types` at the compiled output, so consumers never need the TypeScript sources.
+- Rebuild locally before opening a PR:
+
+  ```bash
+  npm ci
+  npm run build
+  ```
 
-timezones['Custom/Island'] = { sdt: 32_400, dst: 36_000 }; // Offsets in seconds
+- Publishing to npm is handled by the maintainers. Contributors can stop at the build step and submit a pull request.
 
-const island = new DateTz(Date.now(), 'Custom/Island');
-```
+---
 
-> Ensure keys follow IANA naming conventions. Offsets are seconds from UTC (negative for west, positive for east).
+## TypeScript & Tooling
 
-## TypeScript Excellence
+- `IDateTz` describes constructor-friendly shapes.
+- `timezones` exports the full offset map (`Record<string, { sdt: number; dst: number }>`).
+- Compatible with bundlers (Webpack, Vite, TurboPack). For ESM projects, use transpilation or `dynamic import`.
 
 ```ts
 import type { IDateTz } from '@lbd-sh/date-tz';
 
-function normalise(date: IDateTz): IDateTz {
-  const instance = new DateTz(date);
-  return instance.cloneToTimezone('UTC');
+function normalise(input: IDateTz): IDateTz {
+  return new DateTz(input).cloneToTimezone('UTC');
 }
 ```
 
-`IDateTz` lets you accept plain objects from APIs while still benefiting from compile-time guarantees.
-
-## Interoperability Patterns
+---
 
-### With Fetch / APIs
+## Performance Tips
 
-```ts
-const response = await fetch('/api/events');
-const body: { timestamp: number; timezone: string }[] = await response.json();
+1. **Reuse instances** when adjusting a datetime in a tight loop (mutating via `set`/`add` avoids allocations).
+2. **Cache conversions**: if you often convert the same timestamp across timezones, keep the clones.
+3. **Disable locale formatting** (`toString(pattern)` without the `locale` argument) for the fastest path.
+4. **Tree-shake**: import only what you need (`import { DateTz }` instead of wildcard).
 
-const events = body.map(({ timestamp, timezone }) => new DateTz(timestamp, timezone));
-```
+---
 
-### With Cron-like Scheduling
+## FAQ & Troubleshooting
 
-```ts
-const job = new DateTz(Date.UTC(2025, 5, 1, 5, 0), 'America/New_York');
+**Q: Can I format with seconds or milliseconds?**  
+A: Seconds (`ss`) are supported. Milliseconds are intentionally dropped to keep arithmetic deterministic. Store them separately if needed.
 
-while (job.compare(DateTz.now('America/New_York')) < 0) {
-  job.add(1, 'day');
-}
-```
+**Q: Why can’t I compare two dates with different timezones?**  
+A: `compare` guards against mistakes. Convert one date (`cloneToTimezone`) before comparing.
 
-## Packaging Notes
+**Q: How do I add weeks?**  
+A: Compose calls (`add(7, 'day')`). Weeks are not a native unit to keep the API small and explicit.
 
-- The published CommonJS bundle lives in `dist/index.js`; declarations and maps ship alongside (`index.d.ts`, `*.map`).
-- `package.json` exposes `main` and `types` from the compiled output, so consumers do not need to run TypeScript.
-- Build locally with:
+**Q: Do I need to ship the entire `timezones` map?**  
+A: The map is ~40 KB minified. For extreme optimisation you can pre-prune zones before bundling.
 
-  ```bash
-  npm install
-  npm run build
-  ```
+---
 
-- The GitHub Action (`.github/workflows/production.yaml`) produces the build, versions using GitVersion, and publishes to npm as `@lbd-sh/date-tz`.
+## Contributing
 
-## Roadmap Ideas
+- 💡 Open feature ideas or bug reports at [github.com/lbdsh/date-tz/issues](https://github.com/lbdsh/date-tz/issues).
+- 🔁 Submit pull requests following the existing linting/build steps (`npm ci && npm run build`).
+- 📦 Releases are automated through the GitHub workflow in `.github/workflows/production.yaml`.
 
-- Add optional ESM build targets.
-- Ship a companion utilities layer (diffs, ranges, calendars).
-- Expand token set with `W` (ISO week) and `ddd` (weekday short names).
+Community feedback keeps DateTz sharp—thanks for being part of it! 🙌
 
-Contributions and feature requests are welcome — open an issue at [github.com/lbdsh/date-tz/issues](https://github.com/lbdsh/date-tz/issues).
+---
 
 ## License
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@lbd-sh/date-tz",
   "displayName": "Date TZ",
   "engineStrict": false,
-  "version": "1.0.6",
+  "version": "1.0.8",
   "main": "index.js",
   "types": "index.d.ts",
   "scripts": {