is-mahram
Version:
A TypeScript library to determine if a person is a mahram based on Islamic jurisprudence.
278 lines (198 loc) • 7.26 kB
Markdown
# Mahram Checker (is-mahram)
[](https://badge.fury.io/js/is-mahram)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://github.com/pragusga25/is-mahram/actions)
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
```bash
npm install is-mahram
```
```bash
yarn add is-mahram
```
```bash
pnpm add is-mahram
```
```bash
bun add is-mahram
```
## 🚀 Quick Start
```typescript
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
```typescript
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
```typescript
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.
```typescript
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
```typescript
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
```typescript
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
```typescript
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:
```typescript
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
```bash
# Run tests
bun test
```
## 📋 Requirements
- Node.js 18+
- TypeScript 5.0+
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Setup
```bash
# 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](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](https://github.com/pragusga25/is-mahram)
- [NPM Package](https://www.npmjs.com/package/is-mahram)
- [Issue Tracker](https://github.com/pragusga25/is-mahram/issues)
## 📊 Changelog
See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes.