@tungstenstudio/darts-handicap-calculator 1.0.0-rc.0

package/README.md

@@ -0,0 +1,328 @@
+# @tungstenstudio/darts-handicap-calculator
+
+Handicap calculator for x01 and cricket darts matches. Uses pure ratio methods — no lookup tables, flat offsets, or tiered brackets.
+
+## Install
+
+```sh
+npm i @tungstenstudio/darts-handicap-calculator
+# or
+pnpm add @tungstenstudio/darts-handicap-calculator
+# or
+yarn add @tungstenstudio/darts-handicap-calculator
+# or
+bun add @tungstenstudio/darts-handicap-calculator
+```
+
+## X01 Handicap
+
+Scores are adjusted proportionally by the ratio of player averages (PPD), so both players need roughly the same number of darts to finish.
+
+**Formula:** `adjustedScore = baseScore × (weakerPPD ÷ strongerPPD)`, rounded to the nearest integer.
+
+### Quick Start
+
+```ts
+import { calculateX01Handicap } from '@tungstenstudio/darts-handicap-calculator';
+
+const result = calculateX01Handicap({
+  baseScore: 501,
+  direction: 'negative',
+  averageType: 'ppd',
+  playerA: { value: 22, name: 'Alice' },
+  playerB: { value: 16, name: 'Bob' },
+});
+
+result.playerA.startScore;      // 501  (stronger player keeps base)
+result.playerB.startScore;      // 364  (weaker player starts lower)
+result.handicapPoints;           // 137
+result.playerA.estimatedDarts;   // 23
+result.playerB.estimatedDarts;   // 23
+result.playerA.name;             // 'Alice'
+result.capped;                   // false
+```
+
+#### With a Handicap Cap
+
+```ts
+const result = calculateX01Handicap({
+  baseScore: 501,
+  direction: 'negative',
+  averageType: 'ppd',
+  playerA: { value: 20 },
+  playerB: { value: 10 },
+  maxHandicap: 150,
+});
+
+result.playerA.startScore;  // 501
+result.playerB.startScore;  // 351  (capped — would be 251 without cap)
+result.handicapPoints;       // 150
+result.capped;               // true
+```
+
+#### With Score Rounding
+
+```ts
+const result = calculateX01Handicap({
+  baseScore: 501,
+  direction: 'negative',
+  averageType: 'ppd',
+  playerA: { value: 17 },
+  playerB: { value: 12 },
+  roundTo: 25,
+});
+
+result.playerB.startScore;  // 350  (354 rounded to nearest 25)
+result.rounded;              // true
+```
+
+#### With Handicap Percentage
+
+```ts
+const result = calculateX01Handicap({
+  baseScore: 501,
+  direction: 'negative',
+  averageType: 'ppd',
+  playerA: { value: 20 },
+  playerB: { value: 10 },
+  handicapPercentage: 75,
+});
+
+result.playerB.startScore;  // 313  (75% of 250-point gap applied)
+result.handicapPoints;       // 188
+result.compressed;           // true
+```
+
+### API
+
+#### `calculateX01Handicap(input: X01HandicapInput): X01HandicapResult`
+
+Calculates handicapped start scores for two players.
+
+```ts
+interface X01HandicapInput {
+  baseScore: number;        // The base game score (e.g. 301, 501, 701)
+  direction: Direction;     // 'negative' | 'positive'
+  averageType: AverageType; // 'ppd' | '3da'
+  playerA: PlayerAverage;
+  playerB: PlayerAverage;
+  maxHandicap?: number;     // Optional cap on the handicap spread
+  roundTo?: number;         // Round adjusted score to nearest N (e.g. 5, 10, 25)
+  handicapPercentage?: number; // Apply only N% of the handicap spread (1–100, default: 100)
+}
+
+interface PlayerAverage {
+  value: number;            // The player's average
+  name?: string;            // Optional player name (passed through to result)
+}
+```
+
+Returns:
+
+```ts
+interface X01HandicapResult {
+  baseScore: number;
+  direction: Direction;
+  handicapPoints: number;   // Absolute difference between start scores
+  capped: boolean;          // Whether maxHandicap was applied
+  rounded: boolean;         // Whether roundTo changed the score
+  compressed: boolean;      // Whether handicapPercentage reduced the spread
+  playerA: PlayerResult;
+  playerB: PlayerResult;
+}
+
+interface PlayerResult {
+  startScore: number;       // The handicapped start score
+  ppd: number;              // Points per dart
+  threeDartAverage: number; // 3-dart average
+  estimatedDarts: number;   // Estimated darts to finish (ceil(startScore / ppd))
+  name?: string;            // Player name (if provided in input)
+}
+```
+
+#### Direction
+
+The `direction` parameter controls which player's score is adjusted:
+
+| Direction | Stronger player | Weaker player |
+|-----------|----------------|---------------|
+| `'negative'` | Keeps the base score | Starts **lower** (reduced proportionally) |
+| `'positive'` | Starts **higher** (raised proportionally) | Keeps the base score |
+
+Both directions produce the same *relative* handicap. Choose based on your league's convention:
+- **Negative** is the most common — it keeps the strong player at the standard game score.
+- **Positive** is useful when you want all players to start at *at least* the base score.
+
+## Cricket Handicap
+
+The weaker player starts with "spot marks" — free marks toward closing numbers — so both players need roughly the same number of rounds to close all seven numbers.
+
+**Formula:** `spotMarks = 21 × (1 − weakerAvg ÷ strongerAvg)`, rounded to the nearest integer. The total of 21 represents 3 marks × 7 cricket numbers.
+
+### Quick Start
+
+```ts
+import { calculateCricketHandicap } from '@tungstenstudio/darts-handicap-calculator';
+
+const result = calculateCricketHandicap({
+  averageType: 'mpr',
+  playerA: { value: 3.0, name: 'Alice' },
+  playerB: { value: 2.0, name: 'Bob' },
+});
+
+result.spotMarks;                  // 7
+result.playerA.startingMarks;      // 0   (stronger player starts at 0)
+result.playerB.startingMarks;      // 7   (weaker player gets spot marks)
+result.playerA.estimatedRounds;    // 7
+result.playerB.estimatedRounds;    // 7
+```
+
+#### With a Handicap Cap
+
+```ts
+const result = calculateCricketHandicap({
+  averageType: 'mpr',
+  playerA: { value: 4.0 },
+  playerB: { value: 1.0 },
+  maxHandicap: 10,
+});
+
+result.spotMarks;  // 10  (capped — would be 16 without cap)
+result.capped;     // true
+```
+
+#### With Rounding Mode
+
+```ts
+const result = calculateCricketHandicap({
+  averageType: 'mpr',
+  playerA: { value: 2.5 },
+  playerB: { value: 2.0 },
+  rounding: 'ceil',   // 'round' (default) | 'ceil' | 'floor'
+});
+
+result.spotMarks;  // 5  (4.2 ceiled — would be 4 with default rounding)
+```
+
+#### With Handicap Percentage
+
+```ts
+const result = calculateCricketHandicap({
+  averageType: 'mpr',
+  playerA: { value: 3.0 },
+  playerB: { value: 2.0 },
+  handicapPercentage: 50,
+});
+
+result.spotMarks;   // 4  (50% of 7 spot marks)
+result.compressed;  // true
+```
+
+### API
+
+#### `calculateCricketHandicap(input: CricketHandicapInput): CricketHandicapResult`
+
+Calculates spot marks for two cricket players.
+
+```ts
+interface CricketHandicapInput {
+  averageType: CricketAverageType; // 'mpr' | 'ppd'
+  playerA: PlayerAverage;
+  playerB: PlayerAverage;
+  maxHandicap?: number;            // Optional cap on spot marks
+  rounding?: CricketRounding;      // 'round' (default) | 'ceil' | 'floor'
+  handicapPercentage?: number;     // Apply only N% of the spot marks (1–100, default: 100)
+}
+```
+
+Returns:
+
+```ts
+interface CricketHandicapResult {
+  spotMarks: number;               // Marks spotted to the weaker player
+  capped: boolean;                 // Whether maxHandicap was applied
+  rounding: CricketRounding;       // The rounding mode used
+  compressed: boolean;             // Whether handicapPercentage reduced the spread
+  playerA: CricketPlayerResult;
+  playerB: CricketPlayerResult;
+}
+
+interface CricketPlayerResult {
+  startingMarks: number;           // 0 for stronger player, spotMarks for weaker
+  marksNeeded: number;             // 21 − startingMarks
+  average: number;                 // The player's average
+  averageType: CricketAverageType; // 'mpr' | 'ppd'
+  estimatedRounds: number;         // ceil(marksNeeded / average)
+  name?: string;                   // Player name (if provided in input)
+}
+```
+
+## Utility Functions
+
+#### `ppdTo3DA(ppd: number): number`
+
+Converts points-per-dart to 3-dart average.
+
+```ts
+ppdTo3DA(20); // 60
+```
+
+#### `threeDAToPPD(tda: number): number`
+
+Converts 3-dart average to points-per-dart.
+
+```ts
+threeDAToPPD(60); // 20
+```
+
+## Error Handling
+
+The calculator throws `HandicapError` (extends `Error`) with a `code` property for invalid inputs:
+
+```ts
+import { calculateX01Handicap, HandicapError } from '@tungstenstudio/darts-handicap-calculator';
+
+try {
+  calculateX01Handicap(input);
+} catch (err) {
+  if (err instanceof HandicapError) {
+    console.error(err.code);    // e.g. 'INVALID_PLAYER_A_AVERAGE'
+    console.error(err.message); // Human-readable description
+  }
+}
+```
+
+| Error Code | Cause |
+|------------|-------|
+| `INVALID_BASE_SCORE` | `baseScore` is not a finite positive number |
+| `INVALID_PLAYER_A_AVERAGE` | Player A's average is not a finite positive number |
+| `INVALID_PLAYER_B_AVERAGE` | Player B's average is not a finite positive number |
+| `INVALID_MAX_HANDICAP` | `maxHandicap` is provided but not a finite positive number |
+| `INVALID_ROUND_TO` | `roundTo` is provided but not a finite positive integer |
+| `INVALID_HANDICAP_PERCENTAGE` | `handicapPercentage` is provided but not a finite number between 1 and 100 |
+| `INVALID_ROUNDING` | `rounding` (cricket) is provided but not `'round'`, `'ceil'`, or `'floor'` |
+
+## Types
+
+All TypeScript types are exported for convenience:
+
+```ts
+import type {
+  Direction,
+  AverageType,
+  PlayerAverage,
+  PlayerResult,
+  X01HandicapInput,
+  X01HandicapResult,
+  CricketAverageType,
+  CricketRounding,
+  CricketHandicapInput,
+  CricketPlayerResult,
+  CricketHandicapResult,
+  HandicapErrorCode,
+} from '@tungstenstudio/darts-handicap-calculator';
+```
+
+## License
+
+ISC

package/dist/index.cjs

@@ -0,0 +1,241 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  HandicapError: () => HandicapError,
+  calculateCricketHandicap: () => calculateCricketHandicap,
+  calculateX01Handicap: () => calculateX01Handicap,
+  ppdTo3DA: () => ppdTo3DA,
+  threeDAToPPD: () => threeDAToPPD
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/types.ts
+var HandicapError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "HandicapError";
+  }
+};
+
+// src/conversions.ts
+function ppdTo3DA(ppd) {
+  return ppd * 3;
+}
+function threeDAToPPD(tda) {
+  return tda / 3;
+}
+function toPPD(value, type) {
+  if (type === "3da") return threeDAToPPD(value);
+  if (type === "ppd") return value;
+  throw new Error(`Unknown average type: ${type}`);
+}
+
+// src/x01.ts
+function calculateX01Handicap(input) {
+  const { baseScore, direction, averageType, playerA, playerB, maxHandicap, roundTo, handicapPercentage } = input;
+  if (!Number.isFinite(baseScore) || baseScore <= 0) {
+    throw new HandicapError("baseScore must be a finite positive number", "INVALID_BASE_SCORE");
+  }
+  const ppdA = toPPD(playerA.value, averageType);
+  if (!Number.isFinite(ppdA) || ppdA <= 0) {
+    throw new HandicapError("Player A average must be a finite positive number", "INVALID_PLAYER_A_AVERAGE");
+  }
+  const ppdB = toPPD(playerB.value, averageType);
+  if (!Number.isFinite(ppdB) || ppdB <= 0) {
+    throw new HandicapError("Player B average must be a finite positive number", "INVALID_PLAYER_B_AVERAGE");
+  }
+  if (maxHandicap !== void 0) {
+    if (!Number.isFinite(maxHandicap) || maxHandicap <= 0) {
+      throw new HandicapError("maxHandicap must be a finite positive number", "INVALID_MAX_HANDICAP");
+    }
+  }
+  if (roundTo !== void 0) {
+    if (!Number.isFinite(roundTo) || roundTo <= 0 || !Number.isInteger(roundTo)) {
+      throw new HandicapError("roundTo must be a finite positive integer", "INVALID_ROUND_TO");
+    }
+  }
+  if (handicapPercentage !== void 0) {
+    if (!Number.isFinite(handicapPercentage) || handicapPercentage < 1 || handicapPercentage > 100) {
+      throw new HandicapError("handicapPercentage must be a finite number between 1 and 100", "INVALID_HANDICAP_PERCENTAGE");
+    }
+  }
+  const strongerPPD = Math.max(ppdA, ppdB);
+  const weakerPPD = Math.min(ppdA, ppdB);
+  let strongerStart;
+  let weakerStart;
+  if (direction === "negative") {
+    strongerStart = baseScore;
+    weakerStart = Math.round(baseScore * (weakerPPD / strongerPPD));
+  } else {
+    weakerStart = baseScore;
+    strongerStart = Math.round(baseScore * (strongerPPD / weakerPPD));
+  }
+  let compressed = false;
+  if (handicapPercentage !== void 0 && handicapPercentage < 100) {
+    const rawDiff = Math.abs(strongerStart - weakerStart);
+    const adjustedDiff = Math.round(rawDiff * (handicapPercentage / 100));
+    if (adjustedDiff !== rawDiff) {
+      compressed = true;
+      if (direction === "negative") {
+        weakerStart = strongerStart - adjustedDiff;
+      } else {
+        strongerStart = weakerStart + adjustedDiff;
+      }
+    }
+  }
+  let capped = false;
+  const rawHandicap = Math.abs(strongerStart - weakerStart);
+  if (maxHandicap !== void 0 && rawHandicap > maxHandicap) {
+    capped = true;
+    if (direction === "negative") {
+      weakerStart = strongerStart - maxHandicap;
+    } else {
+      strongerStart = weakerStart + maxHandicap;
+    }
+  }
+  let rounded = false;
+  if (roundTo !== void 0 && roundTo > 1) {
+    if (direction === "negative") {
+      const before = weakerStart;
+      weakerStart = Math.max(roundTo, Math.round(weakerStart / roundTo) * roundTo);
+      rounded = weakerStart !== before;
+    } else {
+      const before = strongerStart;
+      strongerStart = Math.max(roundTo, Math.round(strongerStart / roundTo) * roundTo);
+      rounded = strongerStart !== before;
+    }
+  }
+  const aIsStronger = ppdA >= ppdB;
+  function buildResult(ppd, startScore, avg) {
+    const result = {
+      startScore,
+      ppd,
+      threeDartAverage: ppdTo3DA(ppd),
+      estimatedDarts: Math.ceil(startScore / ppd)
+    };
+    if (avg.name !== void 0) {
+      result.name = avg.name;
+    }
+    return result;
+  }
+  return {
+    baseScore,
+    direction,
+    handicapPoints: Math.abs(strongerStart - weakerStart),
+    capped,
+    rounded,
+    compressed,
+    playerA: buildResult(ppdA, aIsStronger ? strongerStart : weakerStart, playerA),
+    playerB: buildResult(ppdB, aIsStronger ? weakerStart : strongerStart, playerB)
+  };
+}
+
+// src/cricket.ts
+var TOTAL_MARKS = 21;
+var VALID_ROUNDING = ["round", "ceil", "floor"];
+function roundFn(mode) {
+  if (mode === "ceil") return Math.ceil;
+  if (mode === "floor") return Math.floor;
+  return Math.round;
+}
+function calculateCricketHandicap(input) {
+  const { averageType, playerA, playerB, maxHandicap, handicapPercentage } = input;
+  const rounding = input.rounding ?? "round";
+  const avgA = playerA.value;
+  if (!Number.isFinite(avgA) || avgA <= 0) {
+    throw new HandicapError("Player A average must be a finite positive number", "INVALID_PLAYER_A_AVERAGE");
+  }
+  const avgB = playerB.value;
+  if (!Number.isFinite(avgB) || avgB <= 0) {
+    throw new HandicapError("Player B average must be a finite positive number", "INVALID_PLAYER_B_AVERAGE");
+  }
+  if (maxHandicap !== void 0) {
+    if (!Number.isFinite(maxHandicap) || maxHandicap <= 0) {
+      throw new HandicapError("maxHandicap must be a finite positive number", "INVALID_MAX_HANDICAP");
+    }
+  }
+  if (input.rounding !== void 0) {
+    if (!VALID_ROUNDING.includes(input.rounding)) {
+      throw new HandicapError(
+        "rounding must be 'round', 'ceil', or 'floor'",
+        "INVALID_ROUNDING"
+      );
+    }
+  }
+  if (handicapPercentage !== void 0) {
+    if (!Number.isFinite(handicapPercentage) || handicapPercentage < 1 || handicapPercentage > 100) {
+      throw new HandicapError("handicapPercentage must be a finite number between 1 and 100", "INVALID_HANDICAP_PERCENTAGE");
+    }
+  }
+  const strongerAvg = Math.max(avgA, avgB);
+  const weakerAvg = Math.min(avgA, avgB);
+  const rawSpotMarks = TOTAL_MARKS * (1 - weakerAvg / strongerAvg);
+  const round = roundFn(rounding);
+  let spotMarks = round(rawSpotMarks);
+  let compressed = false;
+  if (handicapPercentage !== void 0 && handicapPercentage < 100) {
+    const adjustedMarks = round(spotMarks * (handicapPercentage / 100));
+    if (adjustedMarks !== spotMarks) {
+      compressed = true;
+      spotMarks = adjustedMarks;
+    }
+  }
+  let capped = false;
+  if (maxHandicap !== void 0 && spotMarks > maxHandicap) {
+    capped = true;
+    spotMarks = maxHandicap;
+  }
+  const aIsStronger = avgA >= avgB;
+  function buildResult(avg, isStronger) {
+    const startingMarks = isStronger ? 0 : spotMarks;
+    const marksNeeded = TOTAL_MARKS - startingMarks;
+    const result = {
+      startingMarks,
+      marksNeeded,
+      average: avg.value,
+      averageType,
+      estimatedRounds: Math.ceil(marksNeeded / avg.value)
+    };
+    if (avg.name !== void 0) {
+      result.name = avg.name;
+    }
+    return result;
+  }
+  return {
+    spotMarks,
+    capped,
+    rounding,
+    compressed,
+    playerA: buildResult(playerA, aIsStronger),
+    playerB: buildResult(playerB, !aIsStronger)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  HandicapError,
+  calculateCricketHandicap,
+  calculateX01Handicap,
+  ppdTo3DA,
+  threeDAToPPD
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/types.ts","../src/conversions.ts","../src/x01.ts","../src/cricket.ts"],"sourcesContent":["export type {\n  Direction,\n  AverageType,\n  PlayerAverage,\n  PlayerResult,\n  X01HandicapInput,\n  X01HandicapResult,\n  HandicapErrorCode,\n  CricketAverageType,\n  CricketRounding,\n  CricketHandicapInput,\n  CricketPlayerResult,\n  CricketHandicapResult,\n} from './types.js';\n\nexport { HandicapError } from './types.js';\nexport { ppdTo3DA, threeDAToPPD } from './conversions.js';\nexport { calculateX01Handicap } from './x01.js';\nexport { calculateCricketHandicap } from './cricket.js';\n","/**\n * Controls which player's start score is adjusted.\n *\n * - `'negative'` — The stronger player keeps the base score; the weaker\n *   player's start score is reduced proportionally.\n * - `'positive'` — The weaker player keeps the base score; the stronger\n *   player's start score is raised proportionally.\n */\nexport type Direction = 'positive' | 'negative';\n\nexport type AverageType = 'ppd' | '3da';\n\nexport interface PlayerAverage {\n  value: number;\n  name?: string;\n}\n\nexport interface PlayerResult {\n  startScore: number;\n  ppd: number;\n  threeDartAverage: number;\n  estimatedDarts: number;\n  name?: string;\n}\n\nexport interface X01HandicapInput {\n  baseScore: number;\n  direction: Direction;\n  averageType: AverageType;\n  playerA: PlayerAverage;\n  playerB: PlayerAverage;\n  maxHandicap?: number;\n  roundTo?: number;\n  handicapPercentage?: number;\n}\n\nexport interface X01HandicapResult {\n  baseScore: number;\n  direction: Direction;\n  /** Absolute difference between the two start scores. */\n  handicapPoints: number;\n  /** Whether the handicap was capped by maxHandicap. */\n  capped: boolean;\n  /** Whether the start score was rounded by roundTo. */\n  rounded: boolean;\n  /** Whether handicapPercentage compressed the spread. */\n  compressed: boolean;\n  playerA: PlayerResult;\n  playerB: PlayerResult;\n}\n\nexport type HandicapErrorCode =\n  | 'INVALID_BASE_SCORE'\n  | 'INVALID_PLAYER_A_AVERAGE'\n  | 'INVALID_PLAYER_B_AVERAGE'\n  | 'INVALID_MAX_HANDICAP'\n  | 'INVALID_ROUND_TO'\n  | 'INVALID_ROUNDING'\n  | 'INVALID_HANDICAP_PERCENTAGE';\n\nexport class HandicapError extends Error {\n  constructor(\n    message: string,\n    public readonly code: HandicapErrorCode,\n  ) {\n    super(message);\n    this.name = 'HandicapError';\n  }\n}\n\nexport type CricketAverageType = 'mpr' | 'ppd';\n\nexport type CricketRounding = 'round' | 'ceil' | 'floor';\n\nexport interface CricketHandicapInput {\n  averageType: CricketAverageType;\n  playerA: PlayerAverage;\n  playerB: PlayerAverage;\n  maxHandicap?: number;\n  rounding?: CricketRounding;\n  handicapPercentage?: number;\n}\n\nexport interface CricketPlayerResult {\n  startingMarks: number;\n  marksNeeded: number;\n  average: number;\n  averageType: CricketAverageType;\n  estimatedRounds: number;\n  name?: string;\n}\n\nexport interface CricketHandicapResult {\n  /** Number of marks spotted to the weaker player. */\n  spotMarks: number;\n  /** Whether the handicap was capped by maxHandicap. */\n  capped: boolean;\n  /** The rounding mode used ('round' | 'ceil' | 'floor'). */\n  rounding: CricketRounding;\n  /** Whether handicapPercentage compressed the spread. */\n  compressed: boolean;\n  playerA: CricketPlayerResult;\n  playerB: CricketPlayerResult;\n}\n","import type { AverageType } from './types.js';\n\nexport function ppdTo3DA(ppd: number): number {\n  return ppd * 3;\n}\n\nexport function threeDAToPPD(tda: number): number {\n  return tda / 3;\n}\n\nexport function toPPD(value: number, type: AverageType): number {\n  if (type === '3da') return threeDAToPPD(value);\n  if (type === 'ppd') return value;\n  throw new Error(`Unknown average type: ${type as string}`);\n}\n","import type { X01HandicapInput, X01HandicapResult, PlayerResult, PlayerAverage } from './types.js';\nimport { HandicapError } from './types.js';\nimport { toPPD, ppdTo3DA } from './conversions.js';\n\nexport function calculateX01Handicap(input: X01HandicapInput): X01HandicapResult {\n  const { baseScore, direction, averageType, playerA, playerB, maxHandicap, roundTo, handicapPercentage } = input;\n\n  if (!Number.isFinite(baseScore) || baseScore <= 0) {\n    throw new HandicapError('baseScore must be a finite positive number', 'INVALID_BASE_SCORE');\n  }\n\n  const ppdA = toPPD(playerA.value, averageType);\n  if (!Number.isFinite(ppdA) || ppdA <= 0) {\n    throw new HandicapError('Player A average must be a finite positive number', 'INVALID_PLAYER_A_AVERAGE');\n  }\n\n  const ppdB = toPPD(playerB.value, averageType);\n  if (!Number.isFinite(ppdB) || ppdB <= 0) {\n    throw new HandicapError('Player B average must be a finite positive number', 'INVALID_PLAYER_B_AVERAGE');\n  }\n\n  if (maxHandicap !== undefined) {\n    if (!Number.isFinite(maxHandicap) || maxHandicap <= 0) {\n      throw new HandicapError('maxHandicap must be a finite positive number', 'INVALID_MAX_HANDICAP');\n    }\n  }\n\n  if (roundTo !== undefined) {\n    if (!Number.isFinite(roundTo) || roundTo <= 0 || !Number.isInteger(roundTo)) {\n      throw new HandicapError('roundTo must be a finite positive integer', 'INVALID_ROUND_TO');\n    }\n  }\n\n  if (handicapPercentage !== undefined) {\n    if (!Number.isFinite(handicapPercentage) || handicapPercentage < 1 || handicapPercentage > 100) {\n      throw new HandicapError('handicapPercentage must be a finite number between 1 and 100', 'INVALID_HANDICAP_PERCENTAGE');\n    }\n  }\n\n  const strongerPPD = Math.max(ppdA, ppdB);\n  const weakerPPD = Math.min(ppdA, ppdB);\n\n  let strongerStart: number;\n  let weakerStart: number;\n\n  if (direction === 'negative') {\n    strongerStart = baseScore;\n    weakerStart = Math.round(baseScore * (weakerPPD / strongerPPD));\n  } else {\n    weakerStart = baseScore;\n    strongerStart = Math.round(baseScore * (strongerPPD / weakerPPD));\n  }\n\n  let compressed = false;\n  if (handicapPercentage !== undefined && handicapPercentage < 100) {\n    const rawDiff = Math.abs(strongerStart - weakerStart);\n    const adjustedDiff = Math.round(rawDiff * (handicapPercentage / 100));\n    if (adjustedDiff !== rawDiff) {\n      compressed = true;\n      if (direction === 'negative') {\n        weakerStart = strongerStart - adjustedDiff;\n      } else {\n        strongerStart = weakerStart + adjustedDiff;\n      }\n    }\n  }\n\n  let capped = false;\n  const rawHandicap = Math.abs(strongerStart - weakerStart);\n\n  if (maxHandicap !== undefined && rawHandicap > maxHandicap) {\n    capped = true;\n    if (direction === 'negative') {\n      weakerStart = strongerStart - maxHandicap;\n    } else {\n      strongerStart = weakerStart + maxHandicap;\n    }\n  }\n\n  let rounded = false;\n  if (roundTo !== undefined && roundTo > 1) {\n    if (direction === 'negative') {\n      const before = weakerStart;\n      weakerStart = Math.max(roundTo, Math.round(weakerStart / roundTo) * roundTo);\n      rounded = weakerStart !== before;\n    } else {\n      const before = strongerStart;\n      strongerStart = Math.max(roundTo, Math.round(strongerStart / roundTo) * roundTo);\n      rounded = strongerStart !== before;\n    }\n  }\n\n  const aIsStronger = ppdA >= ppdB;\n\n  function buildResult(ppd: number, startScore: number, avg: PlayerAverage): PlayerResult {\n    const result: PlayerResult = {\n      startScore,\n      ppd,\n      threeDartAverage: ppdTo3DA(ppd),\n      estimatedDarts: Math.ceil(startScore / ppd),\n    };\n    if (avg.name !== undefined) {\n      result.name = avg.name;\n    }\n    return result;\n  }\n\n  return {\n    baseScore,\n    direction,\n    handicapPoints: Math.abs(strongerStart - weakerStart),\n    capped,\n    rounded,\n    compressed,\n    playerA: buildResult(ppdA, aIsStronger ? strongerStart : weakerStart, playerA),\n    playerB: buildResult(ppdB, aIsStronger ? weakerStart : strongerStart, playerB),\n  };\n}\n","import type {\n  CricketHandicapInput,\n  CricketHandicapResult,\n  CricketPlayerResult,\n  CricketAverageType,\n  CricketRounding,\n  PlayerAverage,\n} from './types.js';\nimport { HandicapError } from './types.js';\n\nconst TOTAL_MARKS = 21;\nconst VALID_ROUNDING: CricketRounding[] = ['round', 'ceil', 'floor'];\n\nfunction roundFn(mode: CricketRounding): (n: number) => number {\n  if (mode === 'ceil') return Math.ceil;\n  if (mode === 'floor') return Math.floor;\n  return Math.round;\n}\n\nexport function calculateCricketHandicap(input: CricketHandicapInput): CricketHandicapResult {\n  const { averageType, playerA, playerB, maxHandicap, handicapPercentage } = input;\n  const rounding: CricketRounding = input.rounding ?? 'round';\n\n  const avgA = playerA.value;\n  if (!Number.isFinite(avgA) || avgA <= 0) {\n    throw new HandicapError('Player A average must be a finite positive number', 'INVALID_PLAYER_A_AVERAGE');\n  }\n\n  const avgB = playerB.value;\n  if (!Number.isFinite(avgB) || avgB <= 0) {\n    throw new HandicapError('Player B average must be a finite positive number', 'INVALID_PLAYER_B_AVERAGE');\n  }\n\n  if (maxHandicap !== undefined) {\n    if (!Number.isFinite(maxHandicap) || maxHandicap <= 0) {\n      throw new HandicapError('maxHandicap must be a finite positive number', 'INVALID_MAX_HANDICAP');\n    }\n  }\n\n  if (input.rounding !== undefined) {\n    if (!VALID_ROUNDING.includes(input.rounding)) {\n      throw new HandicapError(\n        \"rounding must be 'round', 'ceil', or 'floor'\",\n        'INVALID_ROUNDING',\n      );\n    }\n  }\n\n  if (handicapPercentage !== undefined) {\n    if (!Number.isFinite(handicapPercentage) || handicapPercentage < 1 || handicapPercentage > 100) {\n      throw new HandicapError('handicapPercentage must be a finite number between 1 and 100', 'INVALID_HANDICAP_PERCENTAGE');\n    }\n  }\n\n  const strongerAvg = Math.max(avgA, avgB);\n  const weakerAvg = Math.min(avgA, avgB);\n\n  // Raw spot marks: 21 × (1 - weaker/stronger)\n  const rawSpotMarks = TOTAL_MARKS * (1 - weakerAvg / strongerAvg);\n\n  // Apply rounding mode\n  const round = roundFn(rounding);\n  let spotMarks = round(rawSpotMarks);\n\n  // Apply handicapPercentage compression\n  let compressed = false;\n  if (handicapPercentage !== undefined && handicapPercentage < 100) {\n    const adjustedMarks = round(spotMarks * (handicapPercentage / 100));\n    if (adjustedMarks !== spotMarks) {\n      compressed = true;\n      spotMarks = adjustedMarks;\n    }\n  }\n\n  // Apply maxHandicap cap\n  let capped = false;\n  if (maxHandicap !== undefined && spotMarks > maxHandicap) {\n    capped = true;\n    spotMarks = maxHandicap;\n  }\n\n  const aIsStronger = avgA >= avgB;\n\n  function buildResult(avg: PlayerAverage, isStronger: boolean): CricketPlayerResult {\n    const startingMarks = isStronger ? 0 : spotMarks;\n    const marksNeeded = TOTAL_MARKS - startingMarks;\n    const result: CricketPlayerResult = {\n      startingMarks,\n      marksNeeded,\n      average: avg.value,\n      averageType,\n      estimatedRounds: Math.ceil(marksNeeded / avg.value),\n    };\n    if (avg.name !== undefined) {\n      result.name = avg.name;\n    }\n    return result;\n  }\n\n  return {\n    spotMarks,\n    capped,\n    rounding,\n    compressed,\n    playerA: buildResult(playerA, aIsStronger),\n    playerB: buildResult(playerB, !aIsStronger),\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,89 @@
+/**
+ * Controls which player's start score is adjusted.
+ *
+ * - `'negative'` — The stronger player keeps the base score; the weaker
+ *   player's start score is reduced proportionally.
+ * - `'positive'` — The weaker player keeps the base score; the stronger
+ *   player's start score is raised proportionally.
+ */
+type Direction = 'positive' | 'negative';
+type AverageType = 'ppd' | '3da';
+interface PlayerAverage {
+    value: number;
+    name?: string;
+}
+interface PlayerResult {
+    startScore: number;
+    ppd: number;
+    threeDartAverage: number;
+    estimatedDarts: number;
+    name?: string;
+}
+interface X01HandicapInput {
+    baseScore: number;
+    direction: Direction;
+    averageType: AverageType;
+    playerA: PlayerAverage;
+    playerB: PlayerAverage;
+    maxHandicap?: number;
+    roundTo?: number;
+    handicapPercentage?: number;
+}
+interface X01HandicapResult {
+    baseScore: number;
+    direction: Direction;
+    /** Absolute difference between the two start scores. */
+    handicapPoints: number;
+    /** Whether the handicap was capped by maxHandicap. */
+    capped: boolean;
+    /** Whether the start score was rounded by roundTo. */
+    rounded: boolean;
+    /** Whether handicapPercentage compressed the spread. */
+    compressed: boolean;
+    playerA: PlayerResult;
+    playerB: PlayerResult;
+}
+type HandicapErrorCode = 'INVALID_BASE_SCORE' | 'INVALID_PLAYER_A_AVERAGE' | 'INVALID_PLAYER_B_AVERAGE' | 'INVALID_MAX_HANDICAP' | 'INVALID_ROUND_TO' | 'INVALID_ROUNDING' | 'INVALID_HANDICAP_PERCENTAGE';
+declare class HandicapError extends Error {
+    readonly code: HandicapErrorCode;
+    constructor(message: string, code: HandicapErrorCode);
+}
+type CricketAverageType = 'mpr' | 'ppd';
+type CricketRounding = 'round' | 'ceil' | 'floor';
+interface CricketHandicapInput {
+    averageType: CricketAverageType;
+    playerA: PlayerAverage;
+    playerB: PlayerAverage;
+    maxHandicap?: number;
+    rounding?: CricketRounding;
+    handicapPercentage?: number;
+}
+interface CricketPlayerResult {
+    startingMarks: number;
+    marksNeeded: number;
+    average: number;
+    averageType: CricketAverageType;
+    estimatedRounds: number;
+    name?: string;
+}
+interface CricketHandicapResult {
+    /** Number of marks spotted to the weaker player. */
+    spotMarks: number;
+    /** Whether the handicap was capped by maxHandicap. */
+    capped: boolean;
+    /** The rounding mode used ('round' | 'ceil' | 'floor'). */
+    rounding: CricketRounding;
+    /** Whether handicapPercentage compressed the spread. */
+    compressed: boolean;
+    playerA: CricketPlayerResult;
+    playerB: CricketPlayerResult;
+}
+
+declare function ppdTo3DA(ppd: number): number;
+declare function threeDAToPPD(tda: number): number;
+
+declare function calculateX01Handicap(input: X01HandicapInput): X01HandicapResult;
+
+declare function calculateCricketHandicap(input: CricketHandicapInput): CricketHandicapResult;
+
+export { type AverageType, type CricketAverageType, type CricketHandicapInput, type CricketHandicapResult, type CricketPlayerResult, type CricketRounding, type Direction, HandicapError, type HandicapErrorCode, type PlayerAverage, type PlayerResult, type X01HandicapInput, type X01HandicapResult, calculateCricketHandicap, calculateX01Handicap, ppdTo3DA, threeDAToPPD };