# [TimeAr](https://www.npmjs.com/package/time-ar)

أدوات مصغّرة لـ **الوقت النسبي بالعربية** (مثل «منذ ساعتين»، «الآن»)   . استخدمها حين تحتاج نصوص "منذ متى" بالعربية الفصحى الحديثة، مع مفاتيح تنسيق مكتوبة بالأنواع لتحليل مدخلات التاريخ.

## التثبيت

```bash
npm install time-ar
```


## البداية السريعة

```ts
import timeAr from "time-ar";

const time = timeAr();

const text = time.getTimeAr("21-03-2026 14:30:00", time.format.fullDateTime);

console.log(text)

```


## الأستعمالات

### `timeAr()`

استدعِ التصدير الافتراضي للحصول على كائن يحتوي على:

| الخاصية | النوع | الوصف |
|---------|------|-------|
| `format` | `Property` | كائن يضمّ **أنماط تنسيق التاريخ والوقت** (قيم نصية ثابتة). استخدمها كمعامل ثانٍ لـ `getTimeAr` حتى تُفسَّر المدخلات النصية بشكل متسق. |
| `getTimeAr` | `Function` | دالة تأخذ تاريخًا أو نصًا يمثل تاريخًا، مع تحديد تنسيق مدعوم من `format`، وتعيد نصًا عربيًا يصف الوقت النسبي مثل "الآن"، "منذ 5 دقائق"، أو "منذ يومين". |
| `setTimezone` | `Function` | لي تغير ال `Timezone` المستخدم في حساب الوقت. |

### `getTimeAr(time, timeFormat)`

- **`time`**: كائن `Date` أو نص. للنصوص، يجب أن تطابق القيمةُ النمطَ الذي يعنيه `timeFormat` (انظر الجدول أدناه)، وإلّا سيفشل التحليل.
- **`timeFormat`**: مفتاح من `format` (مثل `shortDate`، `fullDateTime`). هذا هو **تنسيق المدخل** المُمرَّر إلى dayjs للتحليل، وليس تنسيقاً مستقلاً للعرض.

**أمثلة على المخرجات:**

- في غضون نحو 5 ثوانٍ من "الآن": `الآن`
- في غير ذلك: عبارات مثل `منذ ثانية`، `منذ دقيقتين`، `منذ 5 أيام`، `منذ سنة`، مع مراعاة صيغتَي المثنى والجمع في العربية.
- إن لم يُطابق الوقت أيَّ وحدة متوقعة: `منذ مدة`


## مفاتيح التنسيق (`timeAr().format`)

كل مفتاح هو **سلسلة رمز تنسيق dayjs** تُستخدم عند تحليل `time`:

| المفتاح | النمط | شكل المدخل النموذجي |
|--------|------|---------------------|
| `shortDate` | `DD-MM-YYYY` | `21-03-2026` |
| `longDate` | `MMMM D, YYYY` | `March 21, 2026` |
| `shortTime` | `HH:mm` | `14:30` |
| `longTime` | `HH:mm:ss` | `14:30:15` |
| `fullDateTime` | `DD-MM-YYYY HH:mm:ss` | `21-03-2026 14:30:15` |
| `monthDay` | `MMMM D` | `March 21` |
| `monthYear` | `MMMM YYYY` | `March 2026` |
| `dayMonthYear` | `DD/MM/YYYY` | `21/03/2026` |
| `iso8601` | `YYYY-MM-DDTHH:mm:ssZ[Z]` | نصوص محلية شبيهة بـ ISO وفق النمط |
| `time12h` | `hh:mm A` | `02:30 PM` |
| `time12hSeconds` | `hh:mm:ss A` | `02:30:15 PM` |

لاستخدام مفاتيح التنسيق في أنواعك الخاصة، اشتقّها من `format`





## الرخصة

انظر ملف `LICENSE` في جذر الحزمة (إن كان مشمولاً عند النشر).