@gills-pro/sharkjs 0.1.0 → 0.1.1

package/index.d.ts

@@ -0,0 +1,42 @@
+export type * from "./types.js";
+
+import type {
+    BoardInput,
+    EquityRequest,
+    EquityResult,
+    MonteCarloEquityRequest,
+    MonteCarloEquityResult,
+    RuntimeMemoryExports,
+    SharkModuleFactoryOptions,
+    Street,
+} from "./types.js";
+
+export interface SharkModule extends RuntimeMemoryExports {
+    equityExhaustive(hero: string, villain: string, board: string): EquityResult;
+    equityMonteCarlo(
+        hero: string,
+        villain: string,
+        board: string,
+        sampleCount: number,
+        seed: number,
+    ): MonteCarloEquityResult;
+}
+
+export interface Shark extends SharkModule {
+    computeEquity(request: EquityRequest): EquityResult;
+    computeMonteCarloEquity(
+        request: MonteCarloEquityRequest,
+    ): MonteCarloEquityResult;
+}
+
+export declare function normalizeBoard(board: BoardInput | null | undefined): string;
+export declare function countBoardCards(board: BoardInput | null | undefined): 0 | 3 | 4 | 5 | null;
+export declare function getStreet(board: BoardInput | null | undefined): Street | null;
+
+export declare function createRawSharkModule(options?: SharkModuleFactoryOptions): Promise<SharkModule>;
+export declare function createShark(options?: SharkModuleFactoryOptions): Promise<Shark>;
+
+export declare function computeEquity(shark: SharkModule, request: EquityRequest): EquityResult;
+export declare function computeMonteCarloEquity(shark: SharkModule, request: MonteCarloEquityRequest): MonteCarloEquityResult;
+
+export default createShark;

package/index.js

@@ -0,0 +1,120 @@
+let rawFactoryPromise;
+
+function normalizeBoard(board) {
+    if (board == null) {
+        return "";
+    }
+
+    if (typeof board !== "string") {
+        throw new TypeError(`board must be a string, got ${typeof board}`);
+    }
+
+    return board.trim();
+}
+
+function countBoardCards(board) {
+    const normalized = normalizeBoard(board);
+    if (normalized.length === 0) {
+        return 0;
+    }
+
+    const compact = normalized.replaceAll(/\s+/g, "");
+    if (compact.length % 2 !== 0) {
+        return null;
+    }
+
+    const count = compact.length / 2;
+    return count === 3 || count === 4 || count === 5 ? count : null;
+}
+
+function getStreet(board) {
+    switch (countBoardCards(board)) {
+        case 0:
+            return "preflop";
+        case 3:
+            return "flop";
+        case 4:
+            return "turn";
+        case 5:
+            return "river";
+        default:
+            return null;
+    }
+}
+
+function assertRangeInput(label, value) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${label} must be a non-empty range string`);
+    }
+}
+
+function resolveMonteCarloOptions(options) {
+    if (options == null || typeof options !== "object") {
+        throw new TypeError("options must be an object");
+    }
+
+    const sampleCount = Number(options.sampleCount);
+    const seed = Number(options.seed);
+
+    if (!Number.isInteger(sampleCount) || sampleCount <= 0) {
+        throw new TypeError(`options.sampleCount must be a positive integer, got ${String(options.sampleCount)}`);
+    }
+
+    if (!Number.isInteger(seed) || seed < 0) {
+        throw new TypeError(`options.seed must be a non-negative integer, got ${String(options.seed)}`);
+    }
+
+    return { sampleCount, seed };
+}
+
+async function loadRawFactory() {
+    if (!rawFactoryPromise) {
+        rawFactoryPromise = import("./shark_wasm.js").then((module) => module.default);
+    }
+
+    return rawFactoryPromise;
+}
+
+export async function createRawSharkModule(options) {
+    const factory = await loadRawFactory();
+
+    return factory(options);
+}
+
+export function computeEquity(shark, request) {
+    assertRangeInput("request.hero", request?.hero);
+    assertRangeInput("request.villain", request?.villain);
+
+    return shark.equityExhaustive(
+        request.hero,
+        request.villain,
+        normalizeBoard(request.board),
+    );
+}
+
+export function computeMonteCarloEquity(shark, request) {
+    assertRangeInput("request.hero", request?.hero);
+    assertRangeInput("request.villain", request?.villain);
+
+    const options = resolveMonteCarloOptions(request?.options);
+    return shark.equityMonteCarlo(
+        request.hero,
+        request.villain,
+        normalizeBoard(request.board),
+        options.sampleCount,
+        options.seed,
+    );
+}
+
+export async function createShark(options) {
+    const shark = await createRawSharkModule(options);
+
+    shark.computeEquity = (request) => computeEquity(shark, request);
+    shark.computeMonteCarloEquity = (request) => computeMonteCarloEquity(shark, request);
+
+    return shark;
+}
+
+export { countBoardCards, getStreet, normalizeBoard };
+
+export default createShark;

package/package.json

@@ -1,11 +1,26 @@
 {
     "name": "@gills-pro/sharkjs",
-    "version": "0.1.0",
+    "version": "0.1.1",
     "description": "Texas Hold'em poker equity calculator (WebAssembly)",
     "type": "module",
-    "main": "./shark_wasm.js",
-    "types": "./shark_wasm.d.ts",
+    "main": "./index.js",
+    "types": "./index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./index.d.ts",
+            "default": "./index.js"
+        },
+        "./types": {
+            "types": "./types.d.ts",
+            "default": "./types.js"
+        },
+        "./package.json": "./package.json"
+    },
     "files": [
+        "index.js",
+        "index.d.ts",
+        "types.js",
+        "types.d.ts",
         "shark_wasm.js",
         "shark_wasm.wasm",
         "shark_wasm.d.ts"

package/types.d.ts

@@ -0,0 +1,365 @@
+export type CardCode = string;
+export type ComboCode = string;
+export type RangeInput = string;
+export type BoardInput = string;
+
+export type Street = "preflop" | "flop" | "turn" | "river";
+export type ReviewPlayer = "hero" | "villain";
+export type SolverPlayer = "out_of_position" | "in_position" | "none";
+export type NodeType = "action" | "terminal_fold" | "terminal_showdown";
+export type ActionKind = "check" | "bet" | "call" | "raise" | "fold";
+export type EquityMethod = "exhaustive" | "monte_carlo";
+export type RangeGuessSource = "user" | "model" | "preset" | "revealed";
+export type HandClass =
+    | "high_card"
+    | "pair"
+    | "two_pair"
+    | "three_of_a_kind"
+    | "straight"
+    | "flush"
+    | "full_house"
+    | "four_of_a_kind"
+    | "straight_flush";
+export type DrawCategory =
+    | "flush_draw"
+    | "open_ended_straight_draw"
+    | "gutshot"
+    | "overcards"
+    | "pair_plus_draw"
+    | "backdoor_flush_draw"
+    | "backdoor_straight_draw"
+    | "made_hand"
+    | "air";
+
+export interface RuntimeMemoryExports {
+    HEAPF32?: Float32Array;
+    HEAPF64?: Float64Array;
+    HEAP_DATA_VIEW?: DataView;
+    HEAP8?: Int8Array;
+    HEAPU8?: Uint8Array;
+    HEAP16?: Int16Array;
+    HEAPU16?: Uint16Array;
+    HEAP32?: Int32Array;
+    HEAPU32?: Uint32Array;
+    HEAP64?: BigInt64Array;
+    HEAPU64?: BigUint64Array;
+}
+
+export interface SharkModuleFactoryOptions {
+    locateFile?: (path: string, prefix: string) => string;
+    onRuntimeInitialized?: () => void;
+    onAbort?: (reason: unknown) => void;
+    wasmBinary?: ArrayBuffer | Uint8Array;
+    [key: string]: unknown;
+}
+
+export interface EquityResult {
+    equity: number;
+    winWeight: number;
+    tieWeight: number;
+    lossWeight: number;
+    matchupCount: bigint;
+    runoutCount: bigint;
+}
+
+export interface MonteCarloEquityResult extends EquityResult {
+    confidenceLo: number;
+    confidenceHi: number;
+    variance: number;
+    sampleCount: bigint;
+}
+
+export interface MonteCarloOptions {
+    sampleCount: number;
+    seed: number;
+}
+
+export interface EquityRequest {
+    hero: RangeInput;
+    villain: RangeInput;
+    board?: BoardInput;
+}
+
+export interface MonteCarloEquityRequest extends EquityRequest {
+    options: MonteCarloOptions;
+}
+
+export interface ExhaustiveEquitySnapshot extends EquityResult {
+    method: "exhaustive";
+    hero: RangeInput;
+    villain: RangeInput;
+    board: BoardInput;
+}
+
+export interface MonteCarloEquitySnapshot extends MonteCarloEquityResult {
+    method: "monte_carlo";
+    hero: RangeInput;
+    villain: RangeInput;
+    board: BoardInput;
+    options: MonteCarloOptions;
+}
+
+export type EquitySnapshot =
+    | ExhaustiveEquitySnapshot
+    | MonteCarloEquitySnapshot;
+
+export interface RiverSolveRequest {
+    board: BoardInput;
+    outOfPositionRange: RangeInput;
+    inPositionRange: RangeInput;
+    pot: number;
+    effectiveStack: number;
+    betSizes: number[];
+    maxRaises: number;
+    bigBlind: number;
+    iterations: number;
+    convergenceSampleInterval?: number;
+}
+
+export interface SolverResult {
+    iterationsCompleted: number;
+    exploitabilityMbbPerHand: number;
+    outOfPositionStrategy: number[];
+    inPositionStrategy: number[];
+}
+
+export interface ExploitabilityResult {
+    exploitabilityChips: number;
+    exploitabilityMbbPerHand: number;
+    bestResponseEvP0: number;
+    bestResponseEvP1: number;
+}
+
+export interface ConvergenceTrace {
+    exploitabilityPerIteration: number[];
+    strategyDriftPerIteration: number[];
+    sampleInterval: number;
+}
+
+export interface ActionDefinition {
+    index: number;
+    kind: ActionKind;
+    label: string;
+    sizeFraction?: number;
+    amountChips?: number;
+}
+
+export interface StrategyRow {
+    combo: ComboCode;
+    frequencies: number[];
+    weight?: number;
+    handClass?: HandClass;
+}
+
+export interface SolvedNodeStrategy {
+    nodeIndex: number;
+    actingPlayer: SolverPlayer;
+    nodeType: NodeType;
+    potSize: number;
+    actions: ActionDefinition[];
+    rows: StrategyRow[];
+}
+
+export interface TreeNode {
+    nodeType: NodeType;
+    actingPlayer: SolverPlayer;
+    numActions: number;
+    firstChildIndex: number;
+    potSize: number;
+    outOfPositionStreetContribution: number;
+    inPositionStreetContribution: number;
+    foldWinner: SolverPlayer;
+}
+
+export interface GameTree {
+    nodes: TreeNode[];
+    root: number;
+    numActionNodes: number;
+    numTerminalNodes: number;
+    maxDepth: number;
+}
+
+export interface DetailedSolverResult extends SolverResult {
+    exploitability?: ExploitabilityResult;
+    convergenceTrace?: ConvergenceTrace;
+    tree?: GameTree;
+    nodes: SolvedNodeStrategy[];
+}
+
+export interface WeightedCombo {
+    combo: ComboCode;
+    weight: number;
+    live: boolean;
+}
+
+export interface RangeSummary {
+    input: RangeInput;
+    liveComboCount: number;
+    totalMixFrequency: number;
+    weightedComboCount?: number;
+    percentOfComboSpace?: number;
+    topCombos?: WeightedCombo[];
+}
+
+export interface ComboBreakdown {
+    combo: ComboCode;
+    weight: number;
+    equity?: number;
+    handClass?: HandClass;
+    isBlocked?: boolean;
+}
+
+export interface HandClassDistributionEntry {
+    handClass: HandClass;
+    weight: number;
+    comboCount: number;
+    frequency: number;
+}
+
+export interface HandClassDistribution {
+    entries: HandClassDistributionEntry[];
+}
+
+export interface DrawDistributionEntry {
+    draw: DrawCategory;
+    weight: number;
+    comboCount: number;
+    frequency: number;
+}
+
+export interface DrawDistribution {
+    entries: DrawDistributionEntry[];
+}
+
+export interface BlockerEffect {
+    combo: ComboCode;
+    blockedCombos: ComboCode[];
+    blockedCards: CardCode[];
+    removedWeight: number;
+    deltaEquity: number;
+}
+
+export interface BlockerSummary {
+    hero: RangeInput;
+    villain: RangeInput;
+    board: BoardInput;
+    effects: BlockerEffect[];
+    totalBlockedWeight: number;
+}
+
+export interface ActionEvent {
+    street: Street;
+    actor: ReviewPlayer;
+    action: ActionKind;
+    amountChips?: number;
+    potBefore?: number;
+    potAfter?: number;
+    board?: BoardInput;
+    note?: string;
+}
+
+export interface RangeBucketBreakdown {
+    label: string;
+    weight: number;
+    comboCount: number;
+}
+
+export interface StreetRangeGuess {
+    player: ReviewPlayer;
+    street: Street;
+    range: RangeInput;
+    source: RangeGuessSource;
+    note?: string;
+}
+
+export interface RangeEstimate extends StreetRangeGuess {
+    confidence?: number;
+    topCombos?: WeightedCombo[];
+    buckets?: RangeBucketBreakdown[];
+    explanation?: string;
+}
+
+export interface RangeGuessScore {
+    player: ReviewPlayer;
+    street: Street;
+    massOnActualCombo?: number;
+    percentileOfActualCombo?: number;
+    topKHit?: boolean;
+    topK?: number;
+    distanceToPosterior?: number;
+    distanceToRevealedCombo?: number;
+    bucketAccuracy?: number;
+    notes?: string[];
+}
+
+export interface StreetReview {
+    street: Street;
+    board: BoardInput;
+    actions: ActionEvent[];
+    heroGuess?: RangeEstimate;
+    villainGuess?: RangeEstimate;
+    heroModelEstimate?: RangeEstimate;
+    villainModelEstimate?: RangeEstimate;
+    equity?: EquitySnapshot;
+    guessScores?: RangeGuessScore[];
+}
+
+export interface HandReviewResult {
+    streets: StreetReview[];
+    revealedHeroCombo?: ComboCode;
+    revealedVillainCombo?: ComboCode;
+    finalGuessScores: RangeGuessScore[];
+    summary?: string;
+}
+
+export interface ScenarioPreset {
+    id: string;
+    name: string;
+    description?: string;
+    tags?: string[];
+    board?: BoardInput;
+    heroRange?: RangeInput;
+    villainRange?: RangeInput;
+    outOfPositionRange?: RangeInput;
+    inPositionRange?: RangeInput;
+    pot?: number;
+    effectiveStack?: number;
+    betSizes?: number[];
+    maxRaises?: number;
+}
+
+export interface ComparisonCase {
+    label: string;
+    hero: RangeInput;
+    villain: RangeInput;
+    board?: BoardInput;
+    note?: string;
+}
+
+export interface ComparisonEntry<Result> {
+    label: string;
+    result: Result;
+    deltaEquity?: number;
+    deltaWinWeight?: number;
+    deltaTieWeight?: number;
+    deltaLossWeight?: number;
+    note?: string;
+}
+
+export interface ComparisonResult<Result> {
+    baselineLabel?: string;
+    entries: ComparisonEntry<Result>[];
+}
+
+export interface QuizPrompt {
+    id: string;
+    street: Street;
+    kind: "equity" | "pot_odds" | "range_estimation";
+    prompt: string;
+    acceptableRange?: {
+        min: number;
+        max: number;
+    };
+    answer?: string;
+    explanation?: string;
+}

package/types.js

@@ -0,0 +1 @@
+export {};