mmntjs-timezone 0.0.1

package/README.md

@@ -0,0 +1,138 @@
+# mmntjs-timezone
+
+Drop-in replacement for `moment-timezone`.
+
+## Architecture
+
+mmntjs-timezone is moving toward a compatibility-first architecture:
+
+- Moment Timezone compatible packed-data APIs remain the public boundary
+- runtime-loaded zones/links/countries are stored in an internal registry
+- built-in IANA zone fallback currently still uses `Intl` until bundled authoritative data lands
+- the long-term target is full tzdata-backed compatibility with lazy decode and compact storage
+
+```
+moment-timezone          mmntjs-timezone
+     │                        │
+     ├─ packed tzdb      ──   Intl.DateTimeFormat
+     ├─ add/link data    ──   Intl.supportedValuesOf
+     ├─ zone().abbr()    ──   timeZoneName: "short"
+     └─ zone().offset()  ──   formatToParts → UTC comparison
+```
+
+## Behavioral Compatibility
+
+| Feature | Status | Notes |
+|---------|--------|-------|
+| `moment.tz(input, zone)` | ✅ | Parse wall-clock in zone |
+| `moment.tz(input, format, zone)` | ✅ | Parse with format in zone |
+| `moment.tz(input, format, strict, zone)` | ✅ | Strict format dispatch |
+| `moment(ts).tz(zone)` | ✅ | Convert instant to zone |
+| `moment.utc(ts).tz(zone)` | ✅ | Convert UTC to zone |
+| `moment.parseZone(s).tz(zone)` | ✅ | Convert parsed offset to zone |
+| `moment.tz().format("z")` | ✅ | Timezone abbreviation |
+| `moment.tz().format("Z")` | ✅ | Offset display |
+| `moment.tz().utcOffset()` | ✅ | Numeric offset |
+| `moment.tz().zoneAbbr()` | ✅ | Abbreviation API |
+| `moment.tz().zoneName()` | ✅ | Long zone name API |
+| `moment.tz.zone(name)` | ✅ | Zone object API |
+| `moment.tz.names()` | ✅ | List all zone names |
+| `moment.tz.guess()` | ✅ | Runtime timezone detection |
+| `moment.tz.setDefault(z)` | ⚠️ Partial | Stores zone name; apply requires core changes |
+| DST spring-forward | ✅ | Adjusted forward by 1h |
+| DST fall-back | ✅ | First-occurrence (DST side) |
+| `moment.tz(input, zone).valueOf()` | ✅ | Matches moment-timezone |
+| `zone.abbr(ts)` | ✅ | Matches moment-timezone |
+| `zone.offset(ts)` | ✅ | Matches moment-timezone |
+| `zone.utcOffset(ts)` | ✅ | Matches moment-timezone |
+
+### Oracle verification
+
+All behavioral tests compare mmntjs-timezone output against moment-timezone.
+Hand-written expected strings are NOT used for timezone-specific values.
+
+### Deterministic
+
+- Fixed random seed for property tests
+- Cached `Intl.DateTimeFormat` per timezone
+- Offset cache uses `Math.floor(timestamp / 1000)` — deterministic per-second
+- All tests pass across 6 timezone environments (UTC, America/New_York, Europe/Berlin, Asia/Tokyo, Australia/Sydney, America/Los_Angeles)
+
+## Current Status
+
+The package now exposes the core packed-data compatibility APIs and preloads bundled authoritative tzdata generated from `moment-timezone` at build time:
+
+- `moment.tz.add(data)`
+- `moment.tz.link(links)`
+- `moment.tz.load(bundle)`
+- `moment.tz.unpack(data)`
+- `moment.tz.unpackBase60(input)`
+- `moment.tz.countries()`
+- `moment.tz.zonesForCountry(code)`
+
+Current limitation:
+
+- internal storage still uses unpacked JS arrays/objects rather than the planned compact typed-array / lazy-decode representation
+
+### Intl-backed abbreviation limitations
+
+`zone.abbr()` uses `Intl.DateTimeFormat` with `timeZoneName: "short"`. This differs from moment-timezone's packed tzdb:
+
+- **Historical abbreviations**: Intl may not know pre-1970 abbreviations (e.g., "BST" for pre-WW2 London). The oracle tests in `zone-object.test.ts` verify this for epoch=0.
+- **Generic vs standard/daylight**: Some zones return generic "CT" or "MT" instead of "CST"/"CDT" or "EST"/"EDT". `tryLocaleAbbr()` filters out non-standard results via heuristic (2-5 uppercase letters, no "GMT" prefix).
+- **Known overrides**: Zones like `Asia/Taipei`, `Africa/Cairo` use `KNOWN_ABBR` table (line 217) where Intl doesn't provide a short name.
+- **Fallback**: When Intl fails to produce a short name, the abbreviation is synthesized as `GMT{±HHMM}` (e.g., "GMT+0530" for Asia/Kolkata).
+- **Locale probing**: Multiple locales (`en-US`, `ja-JP`, `zh-CN`, etc.) are tried since different locales sometimes yield a short name where others produce a long name. The winning locale is cached per zone.
+
+Abbreviation behavior is oracle-tested against moment-timezone in `regression.test.ts` (including DST transitions and cache ordering).
+
+- **Default timezone**: `moment.tz.setDefault()` stores the zone name. Full integration (making `moment()` respect the default) requires changes to the mmntjs core. The current behavior is:
+  - `moment.defaultZone` is set
+  - `moment.tz(explicit, zone)` still uses the explicit zone
+  - `moment.utc()` is unaffected
+  - `moment()` does NOT automatically create in the default zone
+
+## Testing
+
+```bash
+# Run all tests
+bun test
+
+# Run across 6 timezones
+bash ../../scripts/run-timezone-tests.sh
+
+# Run property tests
+bun test test/property.test.ts
+bun test test/properties-intensive.test.ts
+```
+
+## License
+
+MIT
+
+## Bundle Size
+
+Comparison with original `moment-timezone` (all minified, `bunx tsup --minify`).
+
+### Full data (all historical zones)
+
+| | raw | gzip |
+|---|---|---|
+| `moment-timezone-with-data.min.js` | 710KB | 38KB |
+| `mmntjs-timezone/index.js` (ESM) | **296KB** (−58%) | **35KB** (−8%) |
+
+### 1970–2030 subset
+
+| | raw | gzip |
+|---|---|---|
+| `moment-timezone-with-data-1970-2030.min.js` | 131KB | 20KB |
+| `mmntjs-timezone/1970-2030.js` (ESM) | **78KB** (−40%) | **22KB** (+10%) |
+
+### Logic only (no tzdata, load-your-own)
+
+| | raw | gzip |
+|---|---|---|
+| `moment-timezone.min.js` | 7KB | 3KB |
+| `mmntjs-timezone/logic.js` (ESM) | **12KB** | **4.7KB** |
+
+Both full and 1970–2030 use the same `!D|` delta-encoded binary blob format generated from the upstream `moment-timezone` npm package at build time. The 1970–2030 gzip is 2KB larger because the filter is mechanical (timestamp window) rather than hand-picked like the original.