@lbd-sh/date-tz 1.0.1 → 1.0.2

package/README.md

@@ -1,147 +1,196 @@
-# DateTz Class Documentation
+# Date TZ
 
-## Overview
+Powerful timezone-aware date utilities for JavaScript and TypeScript. `DateTz` keeps timestamps in sync with IANA timezones, handles daylight-saving changes transparently, and exposes a tiny, dependency-free API that stays close to the platform `Date` object while remaining predictable.
 
-The `DateTz` class represents a date and time in a specific timezone. It provides utilities for formatting, parsing, comparing, and manipulating date and time values with full timezone support.
+## Features
 
----
+- Full TypeScript support with `DateTz`, `IDateTz`, and the bundled `timezones` catalog.
+- Minute-precision timestamps normalised to UTC while exposing friendly getters (`year`, `month`, `day`, ...).
+- Formatting and parsing with familiar tokens (`YYYY`, `MM`, `DD`, `HH`, `hh`, `aa`, `tz`, and more).
+- Arithmetic helpers (`add`, `set`) that respect leap years, month lengths, and DST.
+- Instant timezone conversion with `convertToTimezone` and `cloneToTimezone`, backed by automatic DST detection (`Intl.DateTimeFormat`).
+- Works in Node.js and modern browsers without polyfills.
 
-## Constructor
+## Installation
 
-```ts
-new DateTz(value: IDateTz)
-new DateTz(value: number, tz?: string)
+```bash
+npm install @lbd-sh/date-tz
+# or
+yarn add @lbd-sh/date-tz
 ```
 
-- Accepts either an `IDateTz` object or a Unix timestamp with an optional timezone.
-- Throws an error if the provided timezone is invalid.
+## Quick Start
 
----
+```ts
+import { DateTz } from '@lbd-sh/date-tz';
 
-## Properties
+// Create a Rome-based date for 2025-03-01 09:15
+const meeting = new DateTz(Date.UTC(2025, 2, 1, 8, 15), 'Europe/Rome');
 
-### Instance Properties
+meeting.toString();                    // "2025-03-01 09:15:00"
+meeting.toString('DD MMM YYYY HH:mm'); // "01 Mar 2025 09:15"
 
-- `timestamp: number` — Milliseconds since Unix epoch (UTC).
-- `timezone: string` — The timezone identifier (e.g., `"UTC"`, `"Europe/Rome"`).
+// Move the meeting forward and switch to New York time
+meeting.add(1, 'day').add(2, 'hour');
+const nyc = meeting.cloneToTimezone('America/New_York');
 
-### Static Properties
+nyc.toString('YYYY-MM-DD HH:mm tz');   // "2025-03-02 05:15 America/New_York"
+nyc.isDst;                             // true or false depending on the date
+```
 
-- `DateTz.defaultFormat: string` — Default string format pattern: `'YYYY-MM-DD HH:mm:ss'`.
+## Usage
 
----
+### Creating Dates
 
-## Getters
+```ts
+import { DateTz, IDateTz } from '@lbd-sh/date-tz';
 
-- `timezoneOffset: number` — Returns the timezone offset in minutes.
-- `year: number` — Returns the full year.
-- `month: number` — Returns the month (0–11).
-- `day: number` — Returns the day of the month (1–31).
-- `hour: number` — Returns the hour (0–23).
-- `minute: number` — Returns the minute (0–59).
-- `dayOfWeek: number` — Returns the day of the week (0–6).
+new DateTz(Date.now(), 'UTC');
+new DateTz(1719753300000, 'Europe/Rome');
+new DateTz({ timestamp: Date.now(), timezone: 'Asia/Tokyo' } satisfies IDateTz);
 
----
+DateTz.now('America/Los_Angeles');
+```
 
-## Methods
+Notes:
 
-### `compare(other: IDateTz): number`
+- Timestamps are stored in milliseconds since the Unix epoch and are truncated to the nearest minute (`seconds` and `milliseconds` are dropped) for deterministic arithmetic.
+- Timezone identifiers must exist in the bundled `timezones` map; an error is thrown otherwise.
 
-Compares this instance with another `DateTz`. Throws if timezones differ.
+### Formatting
 
-### `isComparable(other: IDateTz): boolean`
+`DateTz.toString` accepts an optional pattern and locale. Unspecified tokens fall back to the default `DateTz.defaultFormat` (`YYYY-MM-DD HH:mm:ss`).
 
-Returns `true` if the two instances share the same timezone.
+```ts
+const invoice = new DateTz(Date.UTC(2025, 5, 12, 12, 0), 'Europe/Paris');
 
-### `toString(pattern?: string): string`
+invoice.toString();                            // "2025-06-12 14:00:00"
+invoice.toString('DD/MM/YYYY HH:mm tz');       // "12/06/2025 14:00 Europe/Paris"
+invoice.toString('LM DD, YYYY hh:mm aa', 'it'); // "Giugno 12, 2025 02:00 pm"
+```
 
-Returns the string representation using the provided format.
+Available tokens:
 
-#### Format Tokens
+| Token | Meaning | Example |
+| ----- | ------- | ------- |
+| `YYYY`, `yyyy` | Full year | `2025` |
+| `YY`, `yy` | Year, two digits | `25` |
+| `MM` | Month (01–12) | `06` |
+| `LM` | Locale month name (capitalised) | `Giugno` |
+| `DD` | Day of month (01–31) | `12` |
+| `HH` | Hours (00–23) | `14` |
+| `hh` | Hours (01–12) | `02` |
+| `mm` | Minutes (00–59) | `00` |
+| `ss` | Seconds (00–59) | `00` |
+| `aa` | `am`/`pm` marker | `pm` |
+| `AA` | `AM`/`PM` marker | `PM` |
+| `tz` | Timezone identifier | `Europe/Paris` |
 
-| Token      | Meaning         |
-| ---------- | --------------- |
-| YYYY, yyyy | Full year       |
-| YY, yy     | Last 2 digits   |
-| MM         | Month (01–12)   |
-| DD         | Day (01–31)     |
-| HH         | Hour (00–23)    |
-| hh         | Hour (01–12)    |
-| mm         | Minute (00–59)  |
-| ss         | Second (00–59)  |
-| aa, AA     | AM/PM marker    |
-| tz         | Timezone string |
+### Parsing strings
 
-### `add(value: number, unit: 'minute' | 'hour' | 'day' | 'month' | 'year'): this`
+`DateTz.parse` mirrors `toString`: pass the source string, its pattern, and an optional timezone (default `UTC`).
 
-Adds the given time to the instance.
+```ts
+import { DateTz } from '@lbd-sh/date-tz';
 
-### `set(value: number, unit: 'year' | 'month' | 'day' | 'hour' | 'minute'): this`
+const parsed = DateTz.parse(
+  '2025-06-12 02:00 PM',
+  'YYYY-MM-DD hh:mm AA',
+  'America/New_York'
+);
 
-Sets a specific part of the date/time.
+parsed.timestamp;     // Milliseconds in UTC (minute precision)
+parsed.timezone;      // "America/New_York"
+parsed.isDst;         // true/false depending on the moment
+```
 
-### `convertToTimezone(tz: string): this`
+> 12-hour patterns require both `hh` and the `AA`/`aa` markers when parsing. If you only need 24-hour formats, prefer `HH`.
 
-Changes the timezone of the instance in place.
+### Arithmetic
 
-### `cloneToTimezone(tz: string): DateTz`
+Mutating helpers operate in-place and normalise overflows:
 
-Returns a new instance in the specified timezone.
+```ts
+const endOfQuarter = new DateTz(Date.UTC(2025, 2, 31, 23, 0), 'UTC');
 
----
+endOfQuarter.add(1, 'day');        // 2025-04-01 23:00
+endOfQuarter.set(6, 'month');      // 2025-06-01 23:00
+endOfQuarter.set(2026, 'year');    // 2026-06-01 23:00
+```
 
-## Static Methods
+All arithmetic respects leap years, month lengths, and daylight-saving changes via the offset cache.
 
-### `DateTz.parse(dateString: string, pattern?: string, tz?: string): DateTz`
+### Comparing
 
-Parses a string to a `DateTz` instance.
+```ts
+const rome = DateTz.now('Europe/Rome');
+const madrid = DateTz.now('Europe/Madrid');
 
-### `DateTz.now(tz?: string): DateTz`
+rome.isComparable(madrid);  // false (different timezones)
 
-Returns the current date/time as a `DateTz` instance.
+const laterInRome = new DateTz(rome.timestamp + 60_000, 'Europe/Rome');
+rome.compare(laterInRome);  // negative number
+```
 
----
+`compare` throws when timezones differ to avoid accidental cross-timezone comparisons. Use `isComparable` first, or convert one date.
 
-## Utility Methods (Private)
+### Timezone conversion
 
-- `stripSMs(timestamp: number): number` — Removes seconds and milliseconds.
-- `isLeapYear(year: number): boolean` — Determines if the year is a leap year.
-- `daysInYear(year: number): number` — Returns days in a year.
+```ts
+const departure = new DateTz(Date.UTC(2025, 4, 15, 6, 45), 'Europe/Rome');
 
----
+departure.isDst; // true/false depending on the date
 
-## Example
+// Modify in place
+departure.convertToTimezone('America/New_York');
 
-```ts
-const dt = new DateTz(1719146400000, 'Europe/Rome');
-console.log(dt.toString());
+// Clone to keep the original instance
+const arrival = departure.cloneToTimezone('Asia/Tokyo');
+```
 
-dt.add(1, 'day');
-console.log(dt.day);
+Timezone changes refresh the internal offset cache and leverage `Intl.DateTimeFormat` when available to detect real-world DST shifts.
 
-const parsed = DateTz.parse("2025-06-23 14:00:00", "YYYY-MM-DD HH:mm:ss", "Europe/Rome");
-console.log(parsed.toString());
+### Accessing components
+
+```ts
+const dt = DateTz.now('UTC');
+
+dt.year;       // e.g. 2025
+dt.month;      // 0-based (0 = January)
+dt.day;        // 1-31
+dt.hour;       // 0-23
+dt.minute;     // 0-59
+dt.dayOfWeek;  // 0 (Sunday) to 6 (Saturday)
+dt.timezone;   // Timezone id provided at creation
+dt.timezoneOffset; // { sdt, dst } seconds from UTC
 ```
 
----
+## Type Definitions
+
+The package ships with comprehensive typings:
 
-## Error Handling
+- `DateTz` implements `IDateTz`.
+- `IDateTz` describes objects that can seed the constructor.
+- `timezones` is a `Record<string, { sdt: number; dst: number }>` that exposes offsets in seconds.
 
-- Throws on invalid timezone.
-- Throws if trying to compare across timezones.
-- Throws if parsing a 12-hour format without AM/PM marker.
+Import what you need:
 
----
+```ts
+import { DateTz, IDateTz, timezones } from '@lbd-sh/date-tz';
+```
 
-## Requirements
+## Timezone catalogue
 
-Requires:
-- `timezones` object mapping timezone identifiers to UTC offsets.
-- `daysPerMonth`, `MS_PER_DAY`, `MS_PER_HOUR`, `MS_PER_MINUTE`, `epochYear` constants.
+- Contains 500+ IANA identifiers with both standard (`sdt`) and daylight (`dst`) offsets in seconds.
+- When `dst === sdt`, the zone does not observe daylight saving time.
+- You can inspect or extend the map in `timezones.ts` before bundling into your application.
 
----
+## Publishing & Packaging
 
-## Summary
+- Build with `npm run build` (TypeScript emits to `dist/` with declarations and source maps).
+- `package.json` maps `main` and `types` to the compiled output, so consumers do not need TypeScript.
+- The GitHub Action (`.github/workflows/production.yaml`) compiles, versions, and publishes to npm as `@lbd-sh/date-tz`.
 
-`DateTz` is ideal for handling precise and consistent date/time values across multiple timezones with customizable formatting, parsing, and manipulation options.
+## License
 
+ISC © lbd-sh

package/package.json

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