Mahram Checker (is-mahram)

A TypeScript library for determining mahram relationships in Islamic law. This library helps identify whether two individuals are mahram (unmarriageable) to each other based on Islamic jurisprudence.

🕌 What is Mahram?

In Islamic law, a mahram is a family member with whom marriage is prohibited. Mahram relationships are established through:

• Blood relations (nasab)
• Marriage relations (musaharah)
• Suckling relations (rada'ah)

📦 Installation

npm install is-mahram

yarn add is-mahram

pnpm add is-mahram

bun add is-mahram

🚀 Quick Start

import { Person, isMahram } from 'is-mahram';

// Create family members
const father = new Person('Ahmad', 'Male');
const mother = new Person('Fatima', 'Female');
const son = new Person('Omar', 'Male');
const daughter = new Person('Aisha', 'Female');

// Set up relationships
son.setFather(father);
son.setMother(mother);
daughter.setFather(father);
daughter.setMother(mother);

// Check mahram relationships
console.log(isMahram(son, father)); // true - father and son
console.log(isMahram(son, daughter)); // true - siblings
console.log(isMahram(son, mother)); // true - mother and son

📖 API Reference

Person Class

The Person class represents an individual with family relationships.

Constructor

new Person(name: string, gender: 'Male' | 'Female')

Methods

| Method | Description | | ------------------------------------- | ----------------------- | | setFather(father: Person) | Sets the father | | setMother(mother: Person) | Sets the mother | | addSpouse(spouse: Person) | Adds a spouse | | setSucklingMother(wetNurse: Person) | Sets suckling mother | | getId() | Returns unique ID | | getName() | Returns name | | getGender() | Returns gender | | getParents() | Returns parents object | | getSpouses() | Returns Set of spouses | | getSucklingMother() | Returns suckling mother |

Example

const person = new Person('Ali', 'Male');
const father = new Person('Hassan', 'Male');
const mother = new Person('Khadija', 'Female');

person.setFather(father);
person.setMother(mother);

isMahram Function

Determines if two people are mahram to each other.

isMahram(personA: Person, personB: Person): boolean

Parameters

• personA: First person
• personB: Second person

Returns

• true if they are mahram
• false if they are not mahram

🔍 Mahram Relationships Covered

Blood Relations (Nasab)

• ✅ Parents, grandparents, great-grandparents
• ✅ Children, grandchildren, great-grandchildren
• ✅ Siblings and half-siblings
• ✅ Aunts and uncles
• ✅ Nephews and nieces

Marriage Relations (Musaharah)

• ✅ Spouses
• ✅ Parents-in-law
• ✅ Children-in-law
• ✅ Step-parents
• ✅ Step-children

Suckling Relations (Rada'ah)

• ✅ Suckling mother
• ✅ Suckling father (husband of suckling mother)
• ✅ Suckling siblings
• ✅ Blood relatives of suckling parents

💡 Usage Examples

Basic Family Tree

import { Person, isMahram } from 'is-mahram';

// Create a family
const grandfather = new Person('Ibrahim', 'Male');
const grandmother = new Person('Maryam', 'Female');
const father = new Person('Ahmed', 'Male');
const uncle = new Person('Omar', 'Male');
const person = new Person('Yusuf', 'Male');
const cousin = new Person('Layla', 'Female');

// Set up relationships
grandfather.addSpouse(grandmother);
father.setFather(grandfather);
father.setMother(grandmother);
uncle.setFather(grandfather);
uncle.setMother(grandmother);
person.setFather(father);
cousin.setFather(uncle);

// Check relationships
console.log(isMahram(person, grandfather)); // true - grandfather
console.log(isMahram(person, uncle)); // true - uncle
console.log(isMahram(person, cousin)); // false - cousin (not mahram)

Marriage Relationships

const man = new Person('Ali', 'Male');
const wife = new Person('Fatima', 'Female');
const motherInLaw = new Person('Khadija', 'Female');

// Set up marriage
man.addSpouse(wife);
wife.setMother(motherInLaw);

console.log(isMahram(man, wife)); // true - spouses
console.log(isMahram(man, motherInLaw)); // true - mother-in-law

Suckling Relationships

const wetNurse = new Person('Umm Salama', 'Female');
const child1 = new Person('Zaid', 'Male');
const child2 = new Person('Ruqayya', 'Female');

// Set up suckling
child1.setSucklingMother(wetNurse);
child2.setSucklingMother(wetNurse);

console.log(isMahram(child1, wetNurse)); // true - suckling mother
console.log(isMahram(child1, child2)); // true - suckling siblings

🛡️ Error Handling

The library includes built-in validation:

import {
  FatherMustBeMaleError,
  MotherMustBeFemaleError,
  SpouseMustBeOppositeGenderError,
  SucklingMotherMustBeFemaleError,
} from 'is-mahram';

try {
  const person = new Person('Ali', 'Male');
  const invalidFather = new Person('Invalid', 'Female');
  person.setFather(invalidFather); // Throws FatherMustBeMaleError
} catch (error) {
  console.log(error.message); // "Father must be male"
}

🧪 Testing

# Run tests
bun test

📋 Requirements

• Node.js 18+
• TypeScript 5.0+

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/pragusga25/is-mahram.git

# Install dependencies
bun

# Run tests
bun test

# Build the library
bun run build

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

📚 Islamic Law References

This library is based on established principles of Islamic jurisprudence regarding mahram relationships. For detailed Islamic law references, please consult:

• Quran and Hadith sources
• Classical Islamic jurisprudence texts
• Contemporary Islamic legal opinions

⚖️ Disclaimer

This library is provided for educational and practical purposes. For matters of Islamic law and religious practice, please consult qualified Islamic scholars and authorities.

🔗 Links

• GitHub Repository
• NPM Package
• Issue Tracker

📊 Changelog

See CHANGELOG.md for a detailed list of changes.