NyotaLab/saa-swahili

Lightweight, zero-dependency utility to parse, convert, manipulate, and format standard timezone dates into localized Swahili Time (Muda wa Kiswahili). # saa-swahili Lightweight, zero-dependency utility to parse, convert, manipulate, and format standard timezone dates into localized **Swahili Time** (*Muda wa Kiswahili*). ## Installation ```bash npm install saa-swahili ``` ## Quick Start ```typescript import { Saa } from 'saa-swahili'; // 14:30 Standard → Saa 8:30 mchana const time = Saa.fromJSDate(new Date(2026, 6, 6, 14, 30)); time.getHour(); // 8 time.getPeriod(); // "mchana" time.format('saa hw mw p'); // "saa nane na nusu mchana" ``` ## How Swahili Time Works Swahili time aligns with the equatorial daylight cycle. The 12-hour cycle resets at 06:00 (sunrise) and 18:00 (sunset): | Standard | Swahili | Formatted | |----------|---------|-----------| | 06:00 AM | 12:00 | Saa kumi na mbili asubuhi | | 07:00 AM | 1:00 | Saa moja asubuhi | | 12:00 PM | 6:00 | Saa sita mchana | | 18:00 PM | 12:00 | Saa kumi na mbili jioni | | 19:00 PM | 1:00 | Saa moja usiku | **Formula:** `SwahiliHour = (StandardHour - 6) mod 12`, adjusted so 0 becomes 12. ### Periods of the Day | Standard Window | Period | Meaning | |-----------------|--------|---------| | 04:00 – 05:59 | `alfajiri` | Dawn | | 06:00 – 11:59 | `asubuhi` | Morning | | 12:00 – 15:59 | `mchana` | Afternoon | | 16:00 – 18:59 | `jioni` | Evening | | 19:00 – 03:59 | `usiku` | Night | ## API ### `Saa.fromJSDate(date: Date, options?: FormatOptions)` Creates a `SaaInstance` from a JavaScript `Date`. ### `SaaInstance.getHour(): number` Returns the Swahili hour (1–12). ### `SaaInstance.getPeriod(): string` Returns the period: `alfajiri`, `asubuhi`, `mchana`, `jioni`, or `usiku`. ### `SaaInstance.format(pattern: string, options?: FormatOptions): string` Formats the time using tokens: | Token | Output | Example | |-------|--------|---------| | `H` | Hour numeral | `1`, `12` | | `HH` | Padded hour | `01`, `12` | | `hw` | Hour in words | `moja`, `kumi na mbili` | | `mm` | Padded mi …