Getting Started

Installation

The engine is a pnpm monorepo. Install dependencies from the root:

pnpm install

TypeScript — flat solver

The simplest path: import solve from @faraid/api.

import { solve, SHAFII } from '@faraid/api';

const result = solve(
  [
    { type: 'Husband',  count: 1 },
    { type: 'Daughter', count: 2 },
    { type: 'Mother',   count: 1 },
  ],
  SHAFII,
);

console.log(result.base); // bigint — asl al-mas'ala
for (const share of result.shares) {
  console.log(share.type, share.sahm, '/', result.base);
}

TypeScript — DAG solver (Munāsakhat / chain of deaths)

For chains of sequential deaths the DAG-based solver auto-reexpresses each heir relative to the sub-deceased:

import { solveChainFromDAG, FamilyBuilder, SHAFII } from '@faraid/api';

const builder = new FamilyBuilder()
  .deceased('Ahmad', 1)           // male
  .addPerson('Maryam', 0)         // wife
  .addPerson('Zayd',   1)         // son
  .addPerson('Hind',   0);        // daughter

builder.addSpouse('Maryam');      // Maryam is Ahmad's spouse

const result = solveChainFromDAG({
  spec: builder.build(),
  deceasedSequence: ['Ahmad', 'Zayd'],
  config: SHAFII,
});

HTTP API

Start the server locally:

pnpm --filter @faraid/server dev
# → http://localhost:8787

curl -X POST http://localhost:8787/solve \
  -H 'content-type: application/json' \
  -d '{"heirs":[{"type":"Husband","count":1},{"type":"Daughter","count":2}]}'

See HTTP Routes for the full API reference.

Madhhab configuration

All four Sunni schools are supported via preset configs:

import { SHAFII, HANAFI, HANBALI, MALIKI } from '@faraid/api';
// or from @faraid/domain directly

The three new extension toggles (D16–D18) control Ḥaml, Khunthā, and Gharqā:

import type { MadhhabConfig } from '@faraid/domain';

const custom: MadhhabConfig = {
  ...SHAFII,
  hamlScenarioSet: 'jumhur_6',          // 6 scenarios (default)
  khunthaAggregation: 'shafii_min',     // component-min
  gharqaMutualInheritance: false,        // Jumhūr ruling
};

Running tests

pnpm -w test    # all packages
pnpm --filter @faraid/core test
pnpm --filter @faraid/api test