time-ar

أول مكتبة npm/cdn عربية مفتوحة المصدر بالشراكة مع الباشمهندس @mahmoudplay لعرض كم مضى & تبقى من الزمن مع التركيز على سلامة اللغة والنحو، مع الامكانية الكاملة فالتخصيص والتعديل.
مثل:

• منذ ساعتين
• بعد 3 أيام
• الآن

تدعم المكتبة ضبط المنطقة الزمنية (Timezone) الافتراضية، مع امكانية التخصيص.

التثبيت

باستخدام npm:

npm i time-ar

باستخدام pnpm:

pnpm add time-ar

باستخدام yarn:

yarn add time-ar

الاستخدام السريع

مثال (JavaScript)

import timeAr from "time-ar";
const time = timeAr();
const text = time.getTimeAr("13:37", time.format.shortTime);
console.log(text)

مثال (TypeScript / ESM)

import timeAr from "time-ar";

const t = timeAr();
const out = t.getTimeAr("21-03-2026 14:30:15", t.format.fullDateTime);
console.log(out); // "منذ ..."/"بعد ..."

واجهة المكتبة (API)

عند استدعاء timeAr() ستحصل على كائن يحتوي على:

• format: مجموعة تنسيقات جاهزة.
• getTimeAr(time, timeFormat): تحويل وقت/تاريخ إلى نص نسبي بالعربية.
• setTimezone(timezone): ضبط التايمزون الافتراضي الذي تُحسب بناءً عليه الفروقات الزمنية.

الدالة getTimeAr

التوقيع

getTimeAr(time: Date | string, timeFormat: string): string

ماذا تُرجع؟

• إذا كان الفرق أقل من 5 ثوانٍ: ترجع "الآن"
• إذا كان التاريخ في الماضي: تبدأ بـ "منذ"
• إذا كان التاريخ في المستقبل: تبدأ بـ "بعد"

ما هو timeFormat؟

هو تنسيق parsing الذي سيتم الاعتماد عليه لفهم قيمة time عندما تكون نصًا (string).

التنسيقات الجاهزة format

هذه هي القيم الجاهزة المتاحة داخل t.format:

إدخال الوقت كـ string (أمثلة عملية)

1) تاريخ كامل

import timeAr from "time-ar";

const t = timeAr();
console.log(t.getTimeAr("21-03-2026 14:30:15", t.format.fullDateTime));

2) تاريخ فقط

import timeAr from "time-ar";

const t = timeAr();
console.log(t.getTimeAr("21-03-2026", t.format.shortDate));

3) وقت فقط (HH:mm أو HH:mm:ss)

إذا مررت وقتًا فقط مثل "14:30" أو "14:30:15" فالمكتبة تعتبره وقت اليوم الحالي في التايمزون الحالي ثم تحسب الفرق مع الآن:

import timeAr from "time-ar";

const t = timeAr();
console.log(t.getTimeAr("14:30", t.format.shortTime));
console.log(t.getTimeAr("14:30:15", t.format.longTime));

ضبط المنطقة الزمنية (Timezone)

افتراضيًا، يتم اختيار التايمزون من نظام التشغيل (أو UTC إذا لم يتوفر). يمكنك تغييره عبر setTimezone:

import timeAr from "time-ar";

const t = timeAr();
t.setTimezone("Africa/Cairo");
// t.setTimezone("Africa/Algiers");
// t.setTimezone("Africa/....");

console.log(t.getTimeAr("21-03-2026 14:30:15", t.format.fullDateTime));

أخطاء متوقعة

• إذا كانت المنطقة الزمنية غير صحيحة، سترمي الدالة خطأ:
  file:///path/index.js:4 t.setTimezone("....المنطقة الخطأ التي وضعتها");

ملاحظات ودقة الإخراج

• التحليل (Parsing) صارم: إذا لم تتطابق قيمة التاريخ النصية مع timeFormat سيتم رمي خطأ مثل:
  Invalid Date: The provided date "..." does not match the format "..." .
• الوحدات المدعومة: ثانية، دقيقة، ساعة، يوم، أسبوع، شهر، سنة.
• صياغة الجمع: يتم تطبيق صيغ عربية مختلفة (مفرد/مثنى/جمع حتى 10/مفرد منصوب بعد 10) مثل:
  منذ ساعة، منذ ساعتين، منذ 3 ساعات، منذ 11 ساعة

أسئلة شائعة

هل المكتبة تُرجع “تنسيق تاريخ” (مثل 21/03/2026)؟

لا. وظيفتها الأساسية الوقت النسبي (منذ/بعد/الآن). أما القيم داخل format فهي قوالب parsing جاهزة لتسهيل إدخال التاريخ/الوقت كسلاسل نصية.

هل أستطيع استخدام تنسيق غير الموجود في format؟

نعم. getTimeAr يقبل أي نص تنسيق يدعمه dayjs (مع customParseFormat).

import timeAr from "time-ar";

const t = timeAr();
console.log(t.getTimeAr("2026|03|21 14-30-15", "YYYY|MM|DD HH-mm-ss"));