محرّك الإجازات الخاصة في السعودية بـ TypeScript (المواد 113 و114 و115 و160)

// src/special-leave/types.ts
export type Religion = 'muslim' | 'non-muslim';
export type Relation = 'spouse' | 'ascendant' | 'descendant' | 'sibling';
export type MonthBasis = 'statutory' | 'calendar';
 
export type Employment = {
  hiredOn: string;
  religion: Religion;
  performedHajjBefore: boolean;
  hajjLeaveUsedInService: boolean;
  enrolmentApproved: boolean;
  // Art. 2: a month is 30 days unless the contract or the work
  // regulations say otherwise. Use 'calendar' only if yours do.
  monthBasis: MonthBasis;
};
 
export type Event =
  | { kind: 'marriage'; on: string; requestedStart?: string }
  | { kind: 'newborn'; on: string; requestedStart?: string }
  | { kind: 'bereavement'; on: string; relation: Relation; requestedStart?: string }
  | { kind: 'iddah'; on: string; pregnant?: boolean; deliveryOn?: string }
  | { kind: 'hajj'; on: string; requestedDays?: number }
  | { kind: 'exam'; on: string; examDays: number; repeatYear: boolean };
 
export type Award = {
  article: string;
  paidDays: number;
  unpaidDays: number;
  startsOn: string | null;
  endsOn: string | null;
  deductsFromAnnual: boolean;
  notes: string[];
  refused?: string;
};

// src/special-leave/dates.ts
const MS_DAY = 86_400_000;
 
export const parseDate = (iso: string) => {
  const [y, m, d] = iso.split('-').map(Number);
  return new Date(Date.UTC(y, m - 1, d));
};
 
export const toISO = (d: Date) => d.toISOString().slice(0, 10);
 
export const addDays = (iso: string, n: number) =>
  toISO(new Date(parseDate(iso).getTime() + n * MS_DAY));
 
export const daysBetween = (a: string, b: string) =>
  Math.round((parseDate(b).getTime() - parseDate(a).getTime()) / MS_DAY);
 
export function addMonths(iso: string, n: number): string {
  const d = parseDate(iso);
  const day = d.getUTCDate();
  const t = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + n, 1));
  const last = new Date(Date.UTC(t.getUTCFullYear(), t.getUTCMonth() + 1, 0)).getUTCDate();
  t.setUTCDate(Math.min(day, last));
  return toISO(t);
}
 
export const overlapDays = (aS: string, aE: string, bS: string, bE: string) => {
  const s = Math.max(parseDate(aS).getTime(), parseDate(bS).getTime());
  const e = Math.min(parseDate(aE).getTime(), parseDate(bE).getTime());
  return e < s ? 0 : Math.round((e - s) / MS_DAY) + 1;
};

// src/special-leave/constants.ts
import type { Relation } from './types';
 
export const BEREAVEMENT_DAYS: Record<Relation, number> = {
  spouse: 5,      // Art. 113
  ascendant: 5,   // parents, grandparents
  descendant: 5,  // children, grandchildren
  sibling: 3,     // brother or sister
};
 
export const MARRIAGE_DAYS = 5;                 // Art. 113
export const NEWBORN_DAYS = 3;                  // Art. 113
export const NEWBORN_CLAIM_WINDOW_DAYS = 7;     // Art. 113 — from the date of birth
 
export const STATUTORY_MONTH_DAYS = 30;         // Art. 2 — unless the contract says otherwise
 
export const IDDAH_MONTHS = 4;                  // Art. 160
export const IDDAH_EXTRA_DAYS = 10;             // Art. 160
export const IDDAH_NON_MUSLIM_DAYS = 15;        // Art. 160
 
export const HAJJ_MIN_DAYS = 10;                // Art. 114
export const HAJJ_MAX_DAYS = 15;                // Art. 114
export const HAJJ_MIN_TENURE_YEARS = 2;         // Art. 114

// src/special-leave/engine.ts
const refuse = (article: string, why: string): Award => ({
  article, paidDays: 0, unpaidDays: 0, startsOn: null, endsOn: null,
  deductsFromAnnual: false, notes: [], refused: why,
});
 
const span = (start: string, days: number) => ({ start, end: addDays(start, days - 1) });
 
// Art. 113: marriage and bereavement leave "are all counted from the date of
// the event". The period is fixed on the calendar; a late start shortens it.
const fromEvent = (on: string, days: number, requestedStart?: string): Award => {
  const lastDay = addDays(on, days - 1);
  const start = requestedStart ?? on;
  if (daysBetween(on, start) < 0) return refuse('113', 'Leave cannot start before the event.');
  if (daysBetween(start, lastDay) < 0)
    return refuse('113', `All ${days} days ran from ${on} and ended on ${lastDay}.`);
  const paid = daysBetween(start, lastDay) + 1;
  const notes = [`Counted from the date of the event (${on}); ends ${lastDay}.`];
  if (paid < days) notes.push(`${days - paid} of the ${days} days had already elapsed.`);
  return {
    article: '113', paidDays: paid, unpaidDays: 0,
    startsOn: start, endsOn: lastDay, deductsFromAnnual: false, notes,
  };
};
 
// --- marriage ---
case 'marriage': {
  const award = fromEvent(ev.on, MARRIAGE_DAYS, ev.requestedStart);
  award.notes.unshift('The event is the marriage date, not the date of the contract (aqd qiran).');
  return award;
}
 
// --- newborn ---
case 'newborn': {
  const start = ev.requestedStart ?? ev.on;
  const elapsed = daysBetween(ev.on, start);
  if (elapsed < 0) return refuse('113', 'Leave cannot start before the birth.');
  if (elapsed >= NEWBORN_CLAIM_WINDOW_DAYS)
    return refuse('113', `Claim window of ${NEWBORN_CLAIM_WINDOW_DAYS} days from birth has expired.`);
  const { end } = span(start, NEWBORN_DAYS);
  return {
    article: '113', paidDays: NEWBORN_DAYS, unpaidDays: 0,
    startsOn: start, endsOn: end, deductsFromAnnual: false,
    notes: [`Started on day ${elapsed} of the 7-day window.`],
  };
}
 
// --- bereavement ---
case 'bereavement': {
  const days = BEREAVEMENT_DAYS[ev.relation];
  const award = fromEvent(ev.on, days, ev.requestedStart);
  award.notes.unshift(`Relation '${ev.relation}' carries ${days} days.`);
  return award;
}

case 'iddah': {
  if (emp.religion === 'non-muslim') {
    const { start, end } = span(ev.on, IDDAH_NON_MUSLIM_DAYS);
    return {
      article: '160', paidDays: IDDAH_NON_MUSLIM_DAYS, unpaidDays: 0,
      startsOn: start, endsOn: end, deductsFromAnnual: false,
      notes: ['Non-Muslim widow: 15 days at full pay.'],
    };
  }
 
  // Art. 2 fixes the month at 30 days unless the contract says otherwise.
  const full = emp.monthBasis === 'calendar'
    ? daysBetween(ev.on, addDays(addMonths(ev.on, IDDAH_MONTHS), IDDAH_EXTRA_DAYS))
    : IDDAH_MONTHS * STATUTORY_MONTH_DAYS + IDDAH_EXTRA_DAYS;
  const notes = [`Four months and ten days on a ${emp.monthBasis} month basis = ${full} days.`];
 
  if (ev.pregnant && ev.deliveryOn && daysBetween(ev.on, ev.deliveryOn) >= 0) {
    const toDelivery = daysBetween(ev.on, ev.deliveryOn) + 1; // delivery day included
    if (toDelivery < full) {
      notes.push('Delivered inside the iddah: the remainder lapses at delivery.');
      return {
        article: '160', paidDays: toDelivery, unpaidDays: 0,
        startsOn: ev.on, endsOn: ev.deliveryOn, deductsFromAnnual: false, notes,
      };
    }
    if (toDelivery > full) {
      const unpaid = toDelivery - full;
      notes.push(`Pregnant: unpaid extension of ${unpaid} days to delivery.`);
      return {
        article: '160', paidDays: full, unpaidDays: unpaid,
        startsOn: ev.on, endsOn: ev.deliveryOn, deductsFromAnnual: false, notes,
      };
    }
  }
 
  return {
    article: '160', paidDays: full, unpaidDays: 0,
    startsOn: ev.on, endsOn: addDays(ev.on, full - 1), deductsFromAnnual: false, notes,
  };
}

case 'hajj': {
  const tenureDays = daysBetween(emp.hiredOn, ev.on);
  if (tenureDays < HAJJ_MIN_TENURE_YEARS * 365)
    return refuse('114', 'Requires two continuous years with the same employer.');
  if (emp.performedHajjBefore)
    return refuse('114', 'Worker has already performed Hajj.');
  if (emp.hajjLeaveUsedInService)
    return refuse('114', 'Hajj leave is once for the whole service.');
 
  const granted = Math.min(
    HAJJ_MAX_DAYS,
    Math.max(HAJJ_MIN_DAYS, ev.requestedDays ?? HAJJ_MIN_DAYS),
  );
  const { start, end } = span(ev.on, granted);
 
  const eid = holidays
    .filter((h) => h.name === 'eid-al-adha')
    .reduce((n, h) => n + overlapDays(start, end, h.start, addDays(h.start, h.days - 1)), 0);
 
  const notes = [`Granted ${granted} days, of which ${eid} fall inside the Eid al-Adha holiday.`];
  if (eid) notes.push('Eid days are already paid as a public holiday and are not paid twice.');
 
  return {
    article: '114', paidDays: granted - eid, unpaidDays: 0,
    startsOn: start, endsOn: end, deductsFromAnnual: false, notes,
  };
}

export type Holiday = { name: string; start: string; days: number };
 
// Replace with the officially announced dates each year — these are astronomical
// estimates and the announced dates routinely differ by a day.
export const HOLIDAYS_2026: Holiday[] = [
  { name: 'eid-al-adha', start: '2026-05-27', days: 4 },
];

case 'exam': {
  if (!emp.enrolmentApproved)
    return refuse('115', 'Employer never approved the enrolment, so no entitlement arises.');
 
  const { start, end } = span(ev.on, ev.examDays);
 
  return ev.repeatYear
    ? {
        article: '115', paidDays: 0, unpaidDays: ev.examDays,
        startsOn: start, endsOn: end, deductsFromAnnual: false,
        notes: ['Repeated year: leave is owed, but unpaid.'],
      }
    : {
        article: '115', paidDays: ev.examDays, unpaidDays: 0,
        startsOn: start, endsOn: end, deductsFromAnnual: false,
        notes: ['Non-repeated year: actual exam days at full pay.'],
      };
}

export function awardSpecialLeave(
  emp: Employment,
  ev: Event,
  holidays: Holiday[] = [],
): Award {
  switch (ev.kind) {
    // ... the six cases from Steps 4 to 7
  }
}

import assert from 'node:assert/strict';
import { awardSpecialLeave, addMonths, type Employment } from './engine.ts';
 
const emp: Employment = {
  hiredOn: '2022-01-10',
  religion: 'muslim',
  performedHajjBefore: false,
  hajjLeaveUsedInService: false,
  enrolmentApproved: true,
  monthBasis: 'statutory',
};
 
// Art. 113 — marriage never touches the annual balance
const marriage = awardSpecialLeave(emp, { kind: 'marriage', on: '2026-03-01' });
assert.equal(marriage.paidDays, 5);
assert.equal(marriage.endsOn, '2026-03-05');
assert.equal(marriage.deductsFromAnnual, false);
 
// Art. 113 — counted from the event: a late start does not move the end
const lateMarriage = awardSpecialLeave(emp,
  { kind: 'marriage', on: '2026-03-01', requestedStart: '2026-03-04' });
assert.equal(lateMarriage.paidDays, 2);
assert.equal(lateMarriage.endsOn, '2026-03-05');
 
// Art. 113 — news of a death that arrives two days late leaves three of five days
const lateNews = awardSpecialLeave(emp,
  { kind: 'bereavement', on: '2026-03-01', relation: 'ascendant', requestedStart: '2026-03-03' });
assert.equal(lateNews.paidDays, 3);
assert.equal(lateNews.endsOn, '2026-03-05');
 
// Art. 113 — the newborn window closes on day 7
const late = awardSpecialLeave(emp, {
  kind: 'newborn', on: '2026-03-01', requestedStart: '2026-03-08',
});
assert.equal(late.paidDays, 0);
assert.match(late.refused!, /window/);
 
// Art. 113 — five days for an ascendant, three for a sibling
assert.equal(awardSpecialLeave(emp,
  { kind: 'bereavement', on: '2026-03-01', relation: 'ascendant' }).paidDays, 5);
assert.equal(awardSpecialLeave(emp,
  { kind: 'bereavement', on: '2026-03-01', relation: 'sibling' }).paidDays, 3);
 
// Art. 2 + 160 — a statutory month is 30 days, so 130 whatever the date
const feb = awardSpecialLeave(emp, { kind: 'iddah', on: '2026-02-01' });
const oct = awardSpecialLeave(emp, { kind: 'iddah', on: '2026-10-01' });
assert.equal(feb.paidDays, 130);
assert.equal(oct.paidDays, 130);
assert.equal(feb.endsOn, '2026-06-10');
 
// ...unless the contract defines the month as a calendar month
const cal: Employment = { ...emp, monthBasis: 'calendar' };
assert.equal(awardSpecialLeave(cal, { kind: 'iddah', on: '2026-10-01' }).paidDays, 133);
 
// Art. 160 — a delivery inside the iddah ends it
const delivered = awardSpecialLeave(emp,
  { kind: 'iddah', on: '2026-02-01', pregnant: true, deliveryOn: '2026-03-02' });
assert.equal(delivered.paidDays, 30);
assert.equal(delivered.unpaidDays, 0);
 
// Art. 114 — fifteen granted days over a four-day Eid cost eleven
const hajj = awardSpecialLeave(emp,
  { kind: 'hajj', on: '2026-05-25', requestedDays: 15 },
  [{ name: 'eid-al-adha', start: '2026-05-27', days: 4 }]);
assert.equal(hajj.paidDays, 11);
 
// Art. 115 — a repeated year is owed, but unpaid
const repeat = awardSpecialLeave(emp,
  { kind: 'exam', on: '2026-06-01', examDays: 4, repeatYear: true });
assert.equal(repeat.paidDays, 0);
assert.equal(repeat.unpaidDays, 4);
 
// month-end clamp
assert.equal(addMonths('2026-01-31', 1), '2026-02-28');