Contribute on GitHub

vani-cycle

Your library predicts periods, ovulation, fertile windows, and detects irregular cycles using clean TypeScript logic.

It’s the female-cycle engine behind apps.

Live Playground

Click "Run Prediction" to see the output.

The 4 Core Concepts

1. Inputs (what the user gives you)

Your library needs only one thing: periodStarts[]

A list of period start dates:

[
  { date: "2024-12-01" },
  { date: "2024-12-29" },
  { date: "2025-01-26" }
]

From this, your library calculates cycle lengths like: 28 days, 28 days, ...

2. Engine (PredictionEngine class)

Users interact with PredictionEngine:

const engine = new PredictionEngine({ strategy: "calendar" });
engine.predictNextPeriod(history);
engine.predictOvulation(history);
engine.predictFertileWindow(history);

The engine:

  • reads the cycle history
  • chooses a prediction strategy
  • calculates expected dates
  • builds confidence
  • adds human-friendly notes

3. Strategies (the brain of predictions)

Right now you support two:

✔️ calendar strategy

Simple average: take all cycle lengths, average them, and add to the last period to predict the next. Works well for regular cycles.

✔️ wma strategy

Weighted moving average: recent cycles have more importance, while old cycles have less. Better accuracy for slight irregularities.

4. What the predictions return

Every prediction returns the same type of structured output:

{
  likely: "2025-02-10",
  window: { start: "2025-02-09", end: "2025-02-11" },
  confidence: 0.76,
  notes: [
    "Your average cycle length is 28 days.",
    "Based on 7 cycles.",
    "Your cycles are very regular. Prediction reliability is high."
  ]
}

likely: The most likely predicted date.

window: A small ± range for safety.

confidence: 0 → low, 1 → high. Shows how stable the user’s cycles are.

notes: Explains the prediction in human language.

The 3 Big Predictions

1. predictNextPeriod(): Finds the next cycle start date. Uses average cycle length, strategy rules, stability of cycles, and interval consistency.

2. predictOvulation(): Ovulation = predicted next period − luteal phase (default 14 days). Returns likely ovulation date, confidence, and notes.

3. predictFertileWindow(): Fertile window = ovulation ± (−5 to +1 days). Returns start, peak, end, and confidence.

Irregularity Check (anomalyCheck)

The simplest part of the library. You calculate cycle lengths: [28, 29, 28, 27, 29]. Then you check if these numbers are close (regular) or jumping (irregular).

const intervals = [20, 40, 35];
anomalyCheck(intervals);

// Returns:
{
  irregular: true,
  message: "Your cycles vary more than usual."
}

This improves the confidence score and the notes.

Daily Logs (Optional Future Data)

Your library supports structured user logs to enable future AI/ML features:

{
  date: "2025-02-10",
  temperature: 97.8,
  cervicalMucus: "creamy",
  stress: 3,
  symptoms: ["headache"]
}

Build & Philosophy

Your library uses a professional setup:

  • TypeScript
  • tsup to build CJS + ESM
  • Tests using Jest
  • Clean src folder structure

Why this library is good:

Small
Predictable
Pure Functions
TypeScript
Testable
Extendable
Simple
Safe

The Simplest "Full Explanation" Ever

You give your library a history of period start dates. It calculates cycle lengths. Then it predicts the next period, ovulation, and fertile window. It checks if the cycles are regular. It returns a date, a window, confidence, and human notes. And everything is TypeScript, clean, and accurate.