texasholdem 1.0.0 → 1.0.3

package/.github/workflows/auto-tag.yml

@@ -0,0 +1,73 @@
+name: Auto-tag & publish on version bump
+
+on:
+  push:
+    branches: [master]
+    paths: [package.json]
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    outputs:
+      changed: ${{ steps.version.outputs.changed }}
+      tag: ${{ steps.version.outputs.tag }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Check if version changed
+        id: version
+        run: |
+          NEW=$(node -p "require('./package.json').version")
+          git checkout HEAD~1 -- package.json 2>/dev/null
+          OLD=$(node -p "require('./package.json').version")
+          git checkout HEAD -- package.json
+          if [ "$OLD" != "$NEW" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            echo "tag=v$NEW" >> "$GITHUB_OUTPUT"
+            echo "Version changed: $OLD -> $NEW"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            echo "Version unchanged: $OLD"
+          fi
+
+      - name: Create and push tag
+        if: steps.version.outputs.changed == 'true'
+        run: |
+          git tag ${{ steps.version.outputs.tag }}
+          git push origin ${{ steps.version.outputs.tag }}
+
+  publish:
+    needs: tag
+    if: needs.tag.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    environment: production
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+          cache: pnpm
+
+      - run: npm install -g npm@latest
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm typecheck
+      - run: pnpm test
+      - run: pnpm build
+
+      - name: Publish with OIDC
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ""

package/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [master]
+  push:
+    branches: [master]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm typecheck
+      - run: pnpm lint
+      - run: pnpm test
+      - run: pnpm build

package/.github/workflows/publish.yml

@@ -5,12 +5,14 @@ on:
     tags:
       - "v*"
 
+permissions:
+  id-token: write
+  contents: read
+
 jobs:
   publish:
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      id-token: write
+    environment: production
     steps:
       - uses: actions/checkout@v4
 
@@ -20,17 +22,17 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 22
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
           cache: pnpm
-          registry-url: https://registry.npmjs.org
 
+      - run: npm install -g npm@latest
       - run: pnpm install --frozen-lockfile
       - run: pnpm typecheck
       - run: pnpm test
       - run: pnpm build
 
-      - run: |
-          echo "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}" >> .npmrc
-          npm publish --provenance --access public
+      - name: Publish with OIDC
+        run: npm publish --provenance --access public
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ""

package/README.md

@@ -28,6 +28,58 @@ pnpm add texasholdem
 
 ## Quick Start
 
+### Strategy-based game loop (recommended)
+
+The simplest way to run poker hands — define a strategy function and let the engine drive the loop:
+
+```typescript
+import { Effect, Either } from "effect";
+import {
+  Chips,
+  SeatIndex,
+  createTable,
+  sitDown,
+  playGame,
+  fromSync,
+  stopAfterHands,
+  Check,
+  Call,
+  Fold,
+} from "texasholdem";
+
+// 1. Create a table and seat players
+let table = Either.getOrThrow(
+  createTable({
+    maxSeats: 6,
+    forcedBets: { smallBlind: Chips(5), bigBlind: Chips(10) },
+  })
+);
+for (const i of [0, 1, 2, 3]) {
+  table = Either.getOrThrow(sitDown(table, SeatIndex(i), Chips(1000)));
+}
+
+// 2. Define a strategy — receives full positional context
+const myStrategy = fromSync((ctx) => {
+  if (ctx.legalActions.canCheck) return Check;
+  return Call;
+});
+
+// 3. Run 100 hands
+const result = Effect.runSync(
+  playGame(myStrategy, {
+    stopWhen: stopAfterHands(100),
+    onEvent: (ev) => console.log(ev._tag),
+    defaultAction: Fold,
+  })(table)
+);
+
+console.log(`Played ${result.handsPlayed} hands`);
+```
+
+### Manual loop (full control)
+
+For UI-driven games, bots with external I/O, or when you need to control each action individually:
+
 ```typescript
 import { Effect, Either, Option } from "effect";
 import {
@@ -39,9 +91,8 @@ import {
   tableAct,
   getActivePlayer,
   getTableLegalActions,
-  Call,
-  Fold,
   Check,
+  Call,
 } from "texasholdem";
 
 // 1. Create a table
@@ -77,7 +128,7 @@ console.log(`Hand finished. Events: ${state.events.length}`);
 
 ## Architecture
 
-12 modules in strict bottom-up dependency order:
+14 modules in strict bottom-up dependency order:
 
 ```
 brand.ts ─── card.ts ─── deck.ts ───────────────────┐
@@ -93,8 +144,12 @@ brand.ts ─── card.ts ─── deck.ts ───────────
    │                   hand.ts ────────────────────────┘
    │                        │
    └─────────────────  table.ts
-                            │
-                        index.ts (barrel exports)
+                         │    │
+                  position.ts  │
+                         │     │
+                       loop.ts
+                         │
+                     index.ts (barrel exports)
 ```
 
 ### Module Summary
@@ -113,9 +168,99 @@ brand.ts ─── card.ts ─── deck.ts ───────────
 | `betting` | Betting round state machine: turn order, completion detection, action validation |
 | `hand` | Full hand lifecycle: Preflop → Flop → Turn → River → Showdown → Complete |
 | `table` | Multi-hand session: seating, button movement, busted player removal |
+| `position` | Positional roles (`Button`, `UTG`, `CO`, …) and `StrategyContext` builder |
+| `loop` | Strategy-driven game loop: `playHand`, `playGame`, timeout/fallback handling |
 
 ## API Overview
 
+### Game Loop (strategy-driven)
+
+The highest-level API — define a strategy function and the engine handles dealing, betting rounds, phase advancement, and multi-hand sessions automatically.
+
+```typescript
+// Strategy receives full context, returns an action
+type Strategy = (ctx: StrategyContext) => Effect.Effect<Action>
+type SyncStrategy = (ctx: StrategyContext) => Action
+
+// Wrap a synchronous function as a Strategy
+fromSync(fn: SyncStrategy): Strategy
+
+// Drive a single hand (table must already have a hand started)
+playOneHand(strategy, opts?): (state: TableState) => Effect<PlayHandResult, PokerError>
+
+// Start + drive a single hand
+playHand(strategy, opts?): (state: TableState) => Effect<PlayHandResult, PokerError>
+
+// Multi-hand loop — keeps dealing until a stop condition is met
+playGame(strategy, opts?): (state: TableState) => Effect<PlayGameResult, PokerError>
+```
+
+**Options:**
+
+```typescript
+interface PlayHandOptions {
+  actionTimeout?: Duration.DurationInput  // e.g. "5 seconds"
+  defaultAction?: Action | ((ctx: StrategyContext) => Action)
+  onEvent?: (event: GameEvent) => void
+  maxActionsPerHand?: number              // default 500 (safety circuit breaker)
+}
+
+interface PlayGameOptions extends PlayHandOptions {
+  stopWhen?: StopCondition
+  maxHands?: number  // default 10_000
+}
+```
+
+**Built-in stop conditions:**
+
+```typescript
+stopAfterHands(n: number): StopCondition
+stopWhenFewPlayers(min?: number): StopCondition  // default min = 2
+```
+
+**Built-in strategies:**
+
+```typescript
+alwaysFold: Strategy      // folds every hand
+passiveStrategy: Strategy // checks when possible, calls otherwise
+```
+
+**Resilience:** when a strategy returns an invalid action, the engine applies a three-level fallback: (1) the returned action, (2) `defaultAction` if provided, (3) Check > Call > Fold. Strategies never need to be defensive about illegal moves.
+
+### Strategy Context
+
+Every strategy call receives a `StrategyContext` — everything a decision-maker needs:
+
+```typescript
+interface StrategyContext {
+  // Identity
+  seat: SeatIndex
+  chips: Chips
+  holeCards: Option<readonly [Card, Card]>
+
+  // Position
+  role: PositionalRole      // "Button" | "SmallBlind" | "BigBlind" | "UTG" | "UTG1" | "UTG2" | "LJ" | "HJ" | "CO"
+  buttonSeat: SeatIndex
+  smallBlindSeat: SeatIndex
+  bigBlindSeat: SeatIndex
+  playersToActAfter: number
+
+  // Hand state
+  phase: Phase              // "Preflop" | "Flop" | "Turn" | "River" | "Showdown" | "Complete"
+  communityCards: Card[]
+  potTotal: Chips
+  bigBlind: Chips
+  activeSeatCount: number   // non-folded, non-busted players
+
+  // Action
+  legalActions: LegalActions
+  players: PlayerView[]     // all players visible state
+  newEvents: GameEvent[]    // events since your last action
+}
+```
+
+Positional roles are assigned automatically based on player count (2–10), following standard poker conventions (heads-up: Button = SB).
+
 ### Table-Level (multi-hand sessions)
 
 ```typescript
@@ -130,6 +275,8 @@ getTableLegalActions(state): Option<LegalActions>
 
 ### Hand-Level (single hand)
 
+Lower-level API for controlling a single hand directly. Most users should prefer the Table or Game Loop API.
+
 ```typescript
 startHand(players, button, forcedBets, handId): Effect<HandState, PokerError>
 act(state, seat, action): Either<HandState, PokerError>
@@ -151,6 +298,39 @@ Raise({ amount }) // Raise over current bet (branded Chips)
 AllIn              // Put all remaining chips in
 ```
 
+### LegalActions
+
+Tells a strategy what moves are currently valid:
+
+```typescript
+interface LegalActions {
+  canFold: boolean
+  canCheck: boolean
+  callAmount: Option<Chips>   // None = no bet to match
+  minBet: Option<Chips>       // available when no prior bet (opening aggression)
+  maxBet: Option<Chips>
+  minRaise: Option<Chips>     // available when a bet already exists
+  maxRaise: Option<Chips>
+  canAllIn: boolean
+  allInAmount: Chips
+}
+```
+
+### Events
+
+Every state change is recorded as a `GameEvent` — a full hand history / audit log:
+
+```typescript
+type GameEvent =
+  | HandStarted | BlindsPosted | HoleCardsDealt
+  | PlayerActed | BettingRoundEnded
+  | CommunityCardsDealt | ShowdownStarted
+  | PotAwarded | HandEnded
+  | PlayerSatDown | PlayerStoodUp
+```
+
+Use `state.events` for table-level events, or the `onEvent` callback in the game loop for real-time streaming.
+
 ## Effect-TS Usage
 
 | Where | What | Why |
@@ -158,6 +338,7 @@ AllIn              // Put all remaining chips in
 | `deck.ts` shuffle | `Effect<Deck>` | Randomness is a side effect |
 | `hand.ts` startHand | `Effect<HandState, PokerError>` | Calls shuffle |
 | `table.ts` startNextHand | `Effect<TableState, PokerError>` | Calls startHand |
+| `loop.ts` playHand / playGame | `Effect<Result, PokerError>` | Orchestrates effectful hand starts + strategy calls |
 | Everything else | Pure functions / `Either` | No side effects needed |
 | Branded types | `Brand.refined` | Compile-time + runtime safety |
 | Errors | `Data.TaggedError` | Pattern-matchable typed errors |

package/eslint.config.js

@@ -49,9 +49,20 @@ export default tseslint.config(
       "@typescript-eslint/no-empty-object-type": "off",
       // Allow non-null assertions where array bounds are checked manually
       "@typescript-eslint/no-non-null-assertion": "warn",
+      // Ban type assertions (as Type) — use type narrowing instead
+      "@typescript-eslint/consistent-type-assertions": [
+        "error",
+        { assertionStyle: "never" },
+      ],
     },
   },
 
+  // Disable type-checked rules for test files (not in tsconfig project)
+  {
+    files: ["test/**/*.ts"],
+    ...tseslint.configs.disableTypeChecked,
+  },
+
   // Prettier — must be last to disable conflicting formatting rules
   prettierConfig,
 );

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "texasholdem",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "Modular, functional Texas Hold'em poker engine built with Effect-TS",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eliraz-refael/texasHoldem-ts.git"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {

package/src/action.ts

@@ -4,9 +4,9 @@
  * @module
  */
 
-import { Data, Either, Match, Option, pipe } from "effect";
+import { Data, Either, Match, Option, Schema, pipe } from "effect";
 import type { Chips } from "./brand.js";
-import { Chips as makeChips, chipsToNumber } from "./brand.js";
+import { Chips as makeChips, chipsToNumber, ChipsSchema } from "./brand.js";
 import { InvalidAction } from "./error.js";
 
 // ---------------------------------------------------------------------------
@@ -49,6 +49,19 @@ export interface LegalActions {
   readonly allInAmount: Chips;
 }
 
+/** Schema for LegalActions — enables composition in StrategyContextSchema and Arbitrary generation. */
+export const LegalActionsSchema = Schema.Struct({
+  canFold: Schema.Boolean,
+  canCheck: Schema.Boolean,
+  callAmount: Schema.Option(ChipsSchema),
+  minBet: Schema.Option(ChipsSchema),
+  maxBet: Schema.Option(ChipsSchema),
+  minRaise: Schema.Option(ChipsSchema),
+  maxRaise: Schema.Option(ChipsSchema),
+  canAllIn: Schema.Boolean,
+  allInAmount: ChipsSchema,
+});
+
 // ---------------------------------------------------------------------------
 // computeLegalActions
 // ---------------------------------------------------------------------------

package/src/betting.ts

@@ -194,7 +194,7 @@ export function applyAction(
   const legal = getLegalActions(state);
   const validated = validateAction(action, legal);
   if (Either.isLeft(validated)) {
-    return validated as Either.Either<never, InvalidAction>;
+    return Either.left(validated.left);
   }
 
   const player = getPlayer(state, seat);

package/src/brand.ts

@@ -51,18 +51,18 @@ export const ZERO_CHIPS: Chips = Chips(0);
 
 /** Add two Chips values. */
 export const addChips = (a: Chips, b: Chips): Chips =>
-  Chips((a as number) + (b as number));
+  Chips(a + b);
 
 /** Subtract `b` from `a`. Caller must ensure `a >= b`. */
 export const subtractChips = (a: Chips, b: Chips): Chips =>
-  Chips((a as number) - (b as number));
+  Chips(a - b);
 
 /** Return the smaller of two Chips values. */
 export const minChips = (a: Chips, b: Chips): Chips =>
-  (a as number) <= (b as number) ? a : b;
+  a <= b ? a : b;
 
 /** Unwrap a Chips value to a plain number. */
-export const chipsToNumber = (c: Chips): number => c as number;
+export const chipsToNumber = (c: Chips): number => c;
 
 /** Order instance for Chips (ascending by numeric value). */
 export const ChipsOrder: Order.Order<Chips> = Order.mapInput(
@@ -106,7 +106,7 @@ export const SeatIndexSchema = Schema.Number.pipe(
 );
 
 /** Unwrap a SeatIndex value to a plain number. */
-export const seatIndexToNumber = (s: SeatIndex): number => s as number;
+export const seatIndexToNumber = (s: SeatIndex): number => s;
 
 /** Order instance for SeatIndex (ascending by numeric value). */
 export const SeatIndexOrder: Order.Order<SeatIndex> = Order.mapInput(

package/src/card.ts

@@ -93,7 +93,9 @@ const CHAR_TO_RANK: Record<string, Rank> = {
   A: 14,
 };
 
-const VALID_SUITS = new Set<string>(SUITS);
+function isSuit(s: string): s is Suit {
+  return SUITS.some((suit) => suit === s);
+}
 
 /**
  * Convert a Card to its two-character pokersolver string.
@@ -139,7 +141,7 @@ export const cardFromString = (s: string): Either.Either<Card, InvalidCard> => {
     );
   }
 
-  if (!VALID_SUITS.has(suitChar)) {
+  if (!isSuit(suitChar)) {
     return Either.left(
       new InvalidCard({
         input: s,
@@ -148,7 +150,7 @@ export const cardFromString = (s: string): Either.Either<Card, InvalidCard> => {
     );
   }
 
-  return Either.right(card(rank, suitChar as Suit));
+  return Either.right(card(rank, suitChar));
 };
 
 /**

package/src/deck.ts

@@ -1,4 +1,4 @@
-import { Array as A, Chunk, Effect, Either, HashMap, Random, pipe } from "effect";
+import { Array as A, Chunk, Effect, Either, HashMap, Random } from "effect";
 import type { Card } from "./card.js";
 import { ALL_CARDS } from "./card.js";
 import type { SeatIndex } from "./brand.js";

package/src/event.ts

@@ -18,7 +18,7 @@ import type { Action } from "./action.js";
 // ---------------------------------------------------------------------------
 
 export type GameEvent = Data.TaggedEnum<{
-  HandStarted: { readonly handId: HandId; readonly button: SeatIndex; readonly players: readonly SeatIndex[] };
+  HandStarted: { readonly handId: HandId; readonly button: SeatIndex; readonly smallBlind: SeatIndex; readonly bigBlind: SeatIndex; readonly players: readonly SeatIndex[] };
   BlindsPosted: { readonly smallBlind: { readonly seat: SeatIndex; readonly amount: Chips }; readonly bigBlind: { readonly seat: SeatIndex; readonly amount: Chips } };
   HoleCardsDealt: { readonly seat: SeatIndex };
   PlayerActed: { readonly seat: SeatIndex; readonly action: Action };

package/src/hand.ts

@@ -10,7 +10,6 @@ import type { Chips, SeatIndex, HandId } from "./brand.js";
 import {
   ZERO_CHIPS,
   minChips,
-  chipsToNumber,
   SeatIndexOrder,
 } from "./brand.js";
 import type { Card } from "./card.js";
@@ -234,7 +233,7 @@ export function startHand(
     const bbAmount = minChips(forcedBets.bigBlind, bbPlayer.chips);
     currentPlayers = updatePlayer(currentPlayers, bbSeat, (p) => placeBet(p, bbAmount));
 
-    events.push(HandStarted({ handId, button, players: seatOrder }));
+    events.push(HandStarted({ handId, button, smallBlind: sbSeat, bigBlind: bbSeat, players: seatOrder }));
     events.push(
       BlindsPosted({
         smallBlind: { seat: sbSeat, amount: sbAmount },

package/src/index.ts

@@ -33,3 +33,23 @@ export {
   getActivePlayer,
   getTableLegalActions,
 } from "./table.js";
+
+export * from "./position.js";
+
+export {
+  type Strategy,
+  type SyncStrategy,
+  type StopCondition,
+  type PlayHandOptions,
+  type PlayHandResult,
+  type PlayGameOptions,
+  type PlayGameResult,
+  fromSync,
+  playOneHand,
+  playHand,
+  playGame,
+  stopAfterHands,
+  stopWhenFewPlayers,
+  alwaysFold,
+  passiveStrategy,
+} from "./loop.js";