@buzzr/dfs-engine
    Preparing search index...

    @buzzr/dfs-engine

    @buzzr/dfs-engine

    npm version ci

    Pure-functional DFS prop grading, payout math, stat normalization, and policy-aware settlement for DFS pick'em apps. PrizePicks and Underdog ship as stable built-ins, and v4 gives you strict settlement inputs, structured validation, and custom book policies without forking. Drop-in TypeScript, zero runtime dependencies, ESM + CJS + .d.ts shipped.

    Sports covered: NBA, WNBA, NCAAM/W, NFL, MLB, NHL, EPL, MLS, La Liga, NWSL, UEFA Champions League. ~70 props.

    npm install @buzzr/dfs-engine

    If you're building a DFS-adjacent tool — a bet tracker, parlay analyzer, EV calculator, social betting app, fantasy coaching tool — you eventually need code that answers:

    • Did this leg hit? Given a player's actual stat and a slip line, decide won / lost / push.
    • What does the slip pay out? Given the play type (Power / Flex / Standard), the pick count, the hits, and any boost, compute the multiplier and the withdrawable-vs-bonus split.
    • What happens when a player doesn't play? Demote a six-pick to a five-pick (PrizePicks) or scratch and rescale (Underdog).
    • What stat goes into a Pts + Rebs + Asts leg? Or Pass + Rush + Rec Yds? Or Hitter FS?

    There's no good open-source TypeScript package for any of this. Everyone reinvents it from scratch, usually wrong. This is the version extracted from Buzzr, where it's been settling real money lines in production. Pure functions, strict runtime validation, and a release suite covering 300+ settlement tests.

    import { gradeLegFromActual } from '@buzzr/dfs-engine';

    // Player scored 28 against a line of 24.5 over → leg won.
    gradeLegFromActual(24.5, 'over', 28);  // 'won'

    // Same line, only 20 → leg lost.
    gradeLegFromActual(24.5, 'over', 20);  // 'lost'

    // Game hasn't ended yet (no stat available) → leg pending.
    gradeLegFromActual(24.5, 'over', null); // 'pending'

    For full-entry settlement, create an isolated engine. Each engine owns its own book policies, payout overrides, league adapters, providers, clock, and audit metadata, so tests, apps, and plugins do not mutate a global registry.

    import { createDfsEngine, defineBookPolicy, definePayoutTable } from '@buzzr/dfs-engine';

    const myBook = defineBookPolicy({
      id: 'my-book',
      displayName: 'My Book',
      version: '2026-05',
      effectiveFrom: '2026-05-01',
      status: 'stable',
      sources: [{ label: 'Internal rules memo' }],
      playTypes: [
        {
          id: 'all-in',
          displayName: 'All-In',
          payoutModel: 'fixed-table',
          pickCount: { min: 2, max: 4 },
          allOrNothing: true,
        },
      ],
      tiePolicy: { type: 'push' },
      dnpPolicy: { type: 'remove_leg', voidIfNoSurvivors: true },
      pushPolicy: { type: 'remove_leg', refundIfNoSurvivors: true },
      payoutSplit: { type: 'all_withdrawable' },
      validation: { duplicatePlayers: 'error' },
    });

    const engine = createDfsEngine({
      bookPolicies: [myBook],
      payoutTables: [
        definePayoutTable({
          bookId: 'my-book',
          playTypeId: 'all-in',
          effectiveFrom: '2026-05-01',
          entries: [{ pickCount: 2, hits: 2, multiplier: 4 }],
        }),
      ],
    });

    const result = await engine.settleEntry(
      {
        entryId: 'slip-1',
        bookId: 'my-book',
        playTypeId: 'all-in',
        stake: 10,
        displayedMultiplier: 4,
        legs: [
          {
            legId: 'a',
            playerName: 'A. Example',
            playerId: 'athlete-1',
            league: 'NBA',
            propType: 'Points',
            line: 24.5,
            direction: 'over',
            actual: null,
            status: 'pending',
            gameDate: '2026-05-07',
          },
          {
            legId: 'b',
            playerName: 'B. Example',
            league: 'NBA',
            propType: 'Rebounds',
            line: 7.5,
            direction: 'over',
            actual: null,
            status: 'pending',
          },
        ],
      },
      { actualsByLegId: { a: 28, b: 9 } },
    );

    console.log(result.status, result.payout, result.policyVersion, result.explanationCodes);

    Legacy app / playType inputs are intentionally not the main v4 model. Use adaptV2EntryInput(...) during migration:

    import { adaptV2EntryInput } from '@buzzr/dfs-engine';

    const v4Input = adaptV2EntryInput({
      entryId: 'legacy-slip',
      app: 'underdog',
      playType: 'underdog_flex',
      stake: 10,
      displayedMultiplier: 11.5,
      legs: [],
    });

    Optional SDK packages:

    • @buzzr/dfs-provider-espn wraps your ESPN-shaped loader as a stat provider.
    • @buzzr/dfs-testkit ships fixture builders and mock providers for settlement tests.
    import { lookupStandardMultiplier } from '@buzzr/dfs-engine';

    // PrizePicks 5-pick Power, all five hit → 20×.
    lookupStandardMultiplier({ app: 'prizepicks', playType: 'power', pickCount: 5, hits: 5 });
    // → 20

    // PrizePicks 6-pick Flex, only 5 of 6 hit → 1.75×.
    lookupStandardMultiplier({ app: 'prizepicks', playType: 'flex', pickCount: 6, hits: 5 });
    // → 1.75

    // Underdog 8-pick Standard, all hit → 100×.
    lookupStandardMultiplier({ app: 'underdog', playType: 'underdog_standard', pickCount: 8, hits: 8 });
    // → 100

    import { recalcMultiplierAfterDnp } from '@buzzr/dfs-engine';

    // One leg on a 6-pick Power scratched. Demote to a 5-pick (all surviving
    // must hit), scaling the slip's original multiplier proportionally so
    // any boost flows through.
    const { newMultiplier } = recalcMultiplierAfterDnp({
      app: 'prizepicks',
      playType: 'power',
      originalPickCount: 6,
      survivingPickCount: 5,
      survivingHits: 5,
      originalMultiplier: 37.5,   // slip-displayed multiplier (post-boost)
    });
    // newMultiplier ≈ 20 (37.5 × 20/37.5)

    recalcMultiplierAfterDnp returns { newMultiplier, usedFallback }. usedFallback is true when the payout table doesn't cover the (app, playType, pickCount, hits) tuple — caller should warn the user that the recompute couldn't be verified.

    3. Extract a stat from a gamelog entry

    The grader needs a numeric value to compare against the line. extractStatForProp handles the prop-string → stat-value mapping across leagues:

    import { extractStatForProp } from '@buzzr/dfs-engine';

    const entry = {
      date: '2026-05-04',
      minutes: '38:21',
      points: '28',
      rebounds: '4',
      assists: '7',
      steals: '1',
      blocks: '0',
      turnovers: '2',
      threeP: '3',
    };

    extractStatForProp('Points', 'NBA', entry, 'prizepicks');          // 28
    extractStatForProp('Pts+Rebs+Asts', 'NBA', entry, 'prizepicks');   // 39
    extractStatForProp('3-Pointers Made', 'NBA', entry, 'prizepicks'); // 3
    extractStatForProp('Rebounds', 'NBA', entry, 'prizepicks');        // 4

    Slip-text aliases are normalized — "3PT Made", "3-pt made", "3ptm", "3pm", "threes" all resolve to '3-Pointers Made'. v0.3 adds 14 new props (Double-Double, Triple-Double, Pts+Stls, Longest Reception/Rush/Pass, MLB Singles/Doubles/Triples/Runs, Pitching Outs, NHL Plus/Minus). See DFS_PROP_TYPE_KEYS for the full canonical list (60+ props across NBA / WNBA / NCAAM/W / NFL / MLB / NHL).

    4. Grade a full entry end-to-end

    gradeDfsBetFromGraded rolls per-leg statuses into a bet-level result with the boost split:

    import { gradeDfsBetFromGraded } from '@buzzr/dfs-engine';

    const result = gradeDfsBetFromGraded({
      app: 'underdog',
      playType: 'underdog_flex',
      legs: [
        { legId: 'a', legStatus: 'won',  /* ...DfsBetLeg fields */ },
        { legId: 'b', legStatus: 'won',  /* ... */ },
        { legId: 'c', legStatus: 'lost', /* ... */ },
        { legId: 'd', legStatus: 'won',  /* ... */ },
        { legId: 'e', legStatus: 'won',  /* ... */ },
      ],
      stake: 10,
      displayedMultiplier: 11.5,      // boosted from base 10×
      baseMultiplier: 10,
      profitBoostPct: null,
    });
    // 4-of-5 Underdog Flex → standard 2×; scaled by displayed/base ratio.
    // → { status: 'won', effectiveMultiplier: 2.3, totalPayout: 23,
    //     withdrawablePayout: 20, bonusPayout: 3 }

    Pending semantics: if any surviving leg is legStatus: 'pending', the whole bet returns status: 'pending' — you can call this every time a leg's actualValue updates without risk of premature settlement.

    Built-in coverage is NBA, WNBA, NCAAM/W, NFL, MLB, NHL. The plugin registry lets you add a sport without forking:

    import {
      registerLeague,
      extractStatForProp,
      type AdapterTable,
    } from '@buzzr/dfs-engine';

    const SOCCER_ADAPTERS: AdapterTable = {
      Goals: (entry) => parseInt(entry.points, 10) || null,
      Assists: (entry) => parseInt(entry.rebounds, 10) || null,
    };

    registerLeague('EPL', SOCCER_ADAPTERS);
    registerLeague('MLS', SOCCER_ADAPTERS);

    extractStatForProp('Goals', 'EPL', someEntry, 'prizepicks'); // your value

    getRegisteredLeagues() returns the current list; unregisterLeague(name) removes one (useful in tests).

    When null isn't specific enough, use the *Explained variants — they return a discriminated union with a reason code so you can show the user why a leg can't be graded yet:

    import {
      extractStatForPropExplained,
      gradeLegFromActualExplained,
    } from '@buzzr/dfs-engine';

    const stat = extractStatForPropExplained('Yellow Cards', 'EPL', entry, 'prizepicks');
    if (!stat.ok) {
      console.log(stat.reason); // 'unknown_prop' | 'unsupported_league' | 'prop_not_supported_for_league' | 'adapter_returned_null'
      console.log(stat.detail); // human-readable context
    }

    const grade = gradeLegFromActualExplained(24.5, 'over', NaN);
    if (!grade.ok) {
      console.log(grade.reason); // 'pending' | 'unparseable_actual'
    }
    Module Highlights
    payouts lookupStandardMultiplier, recalcMultiplierAfterDnp, lookupBaseMultiplier — full PrizePicks (Power/Flex) and Underdog (Standard/Flex) payout schedules
    grading gradeLegFromActual (+Explained), gradeDfsBetFromGraded, applyLegDnp, computeBoostSplit, detectMidGameDnp, reconcileMidGameDnpEntries, findGameLogCandidates, shouldRegradeLeg, extractStatForProp (+Explained)
    prop-normalizer normalizeDfsPropType, asDfsPropTypeKey, DFS_PROP_TYPE_KEYS
    stat-adapters getStatAdapter, extractStatForPropViaRegistry, registerLeague / unregisterLeague / getRegisteredLeagues, plus per-sport tables: BASKETBALL_ADAPTERS, NFL_ADAPTERS, MLB_ADAPTERS, NHL_ADAPTERS
    reconciliation-windows isWithinReconciliationWindow, per-league stat-correction TTLs (NBA 2h, NFL 24h, MLB 6h)
    live-helpers shouldWriteLiveActual, buildLiveSnapshot, buildLiveLegAlertTitle for live-watcher write-paths
    boxscore-shape boxScorePlayerToGameLogShape for sources that only ship some stats on the boxscore (NHL Hits, Blocked Shots)
    validators validateDfsEntryInput, validateDfsLegInput, validateDfsSettlementContext, assertValidDfsEntryInput, and structured validation issues
    types DfsApp, DfsPlayType, DfsLegStatus, DfsBetLeg, DfsLegGameContext, DfsParseResult, LegLinkage, DfsPayoutSplit, BetslipParseMeta, …and ~15 more

    The PlayerGameLogEntryShape the adapters consume is intentionally minimal — define your own gamelog rows that satisfy the shape ({ date, minutes, points, ... }) and pipe them in.

    See CHANGELOG.md for what's new in each release. Looking to contribute? Start at CONTRIBUTING.md. Copy-paste-runnable demos live in examples/README.md. Generated API docs: sarveshsea.github.io/dfs-engine.

    Pure functions, zero deps, sub-microsecond on a Mac M-series (from npm run bench):

    Function ops/sec
    gradeLegFromActual ~24M
    extractStatForPropViaRegistry (NBA Points) ~7.5M
    gradeDfsBetFromGraded (5-pick Power) ~11.5M
    recalcMultiplierAfterDnp ~20M
    applyLegDnp (6-pick) ~5.8M

    Floor numbers — every operation completes in microseconds. You will not be CPU-bound by this library.

    Starting at 1.0, the public API is frozen. Breaking changes only at major versions. New sports, props, and *Explained failure reasons can ship in minor releases without breaking consumers. See CHANGELOG.md for the full stability contract.

    When an LLM, webhook, or cross-process source hands you a slip leg or gamelog entry, run it through the validator before grading:

    import {
      assertValidDfsEntryInput,
      validateDfsEntryInput,
      validatePlayerGameLogEntryShape,
    } from '@buzzr/dfs-engine';

    const v = validatePlayerGameLogEntryShape(maybeEntry);
    if (!v.ok) {
      console.error('Bad gamelog entry:', v.errors);
      return;
    }
    // v.value is now typed as PlayerGameLogEntryShape

    const entry = validateDfsEntryInput(maybeSettlementEntry);
    if (!entry.ok) {
      console.error(entry.errors.map((issue) => [issue.path, issue.code]));
      return;
    }

    assertValidDfsEntryInput(maybeSettlementEntry);

    v4 settlement inputs are canonical: use actual on DfsLegInput, status for leg state, actualsByLegId for settlement context actuals, and legStatusesByLegId for status overrides. Legacy stat, legStatus, statsByLegId, and legStatusByLegId are rejected by the strict validators.

    • Payout tables current as of 2026-05. PrizePicks and Underdog adjust their schedules periodically; if a recalc looks wrong, check whether the published schedule changed.
    • Slip-displayed multiplier always wins. Tables are only the demotion ratio baseline — Demon/Goblin/boost markups aren't enumerated.
    • Gamelog parsing is your problem. This package grades stats; it doesn't fetch them. Adapt ESPN, your own scraper, or a paid data feed to PlayerGameLogEntryShape upstream.
    • Sport coverage: NBA / WNBA / NCAAM (basketball), NFL, MLB (batters + pitchers), NHL (skaters + goalies). Adding a sport means a new AdapterTable plus extending DfsPropTypeKey.

    Extracted from Buzzr, where it settles user bets placed on PrizePicks and Underdog. The Buzzr team has been iterating on this math against real slips and real stat-correction edge cases for two years. The npm package is the same code, just decoupled from the app.

    MIT © Sarvesh Chidambaram

    Settings

    Member Visibility

    On This Page

    @buzzr/dfs-engine