@drmxrcy/tcg-core 0.0.0-202602060542

package/src/zones/zone-operations.ts

@@ -0,0 +1,306 @@
+import { produce } from "immer";
+import seedrandom from "seedrandom";
+import type { CardId } from "../types";
+import type { Zone } from "./zone";
+
+/**
+ * Adds a card to a zone
+ * @param zone - Target zone
+ * @param cardId - Card to add
+ * @param position - Optional position for ordered zones
+ * @returns Updated zone
+ * @throws Error if zone is at maximum size
+ */
+export function addCard(zone: Zone, cardId: CardId, position?: number): Zone {
+  if (
+    zone.config.maxSize !== undefined &&
+    zone.cards.length >= zone.config.maxSize
+  ) {
+    throw new Error(
+      `Cannot add card: zone is at maximum size (${zone.config.maxSize})`,
+    );
+  }
+
+  return produce(zone, (draft) => {
+    if (position !== undefined) {
+      draft.cards.splice(position, 0, cardId);
+    } else {
+      draft.cards.push(cardId);
+    }
+  });
+}
+
+/**
+ * Removes a card from a zone
+ * @param zone - Source zone
+ * @param cardId - Card to remove
+ * @returns Updated zone
+ * @throws Error if card not found in zone
+ */
+export function removeCard(zone: Zone, cardId: CardId): Zone {
+  const index = zone.cards.indexOf(cardId);
+  if (index === -1) {
+    throw new Error(`Card ${cardId} not found in zone ${zone.config.id}`);
+  }
+
+  return produce(zone, (draft) => {
+    draft.cards.splice(index, 1);
+  });
+}
+
+/**
+ * Moves a card from one zone to another
+ * @param fromZone - Source zone
+ * @param toZone - Destination zone
+ * @param cardId - Card to move
+ * @param position - Optional position in destination zone
+ * @returns Updated zones
+ */
+export function moveCard(
+  fromZone: Zone,
+  toZone: Zone,
+  cardId: CardId,
+  position?: number,
+): { fromZone: Zone; toZone: Zone } {
+  const updatedFrom = removeCard(fromZone, cardId);
+  const updatedTo = addCard(toZone, cardId, position);
+
+  return {
+    fromZone: updatedFrom,
+    toZone: updatedTo,
+  };
+}
+
+/**
+ * Draws cards from deck to hand
+ * @param deck - Source deck zone
+ * @param hand - Destination hand zone
+ * @param count - Number of cards to draw
+ * @returns Updated zones and drawn cards
+ * @throws Error if not enough cards in deck
+ */
+export function draw(
+  deck: Zone,
+  hand: Zone,
+  count: number,
+): { fromZone: Zone; toZone: Zone; drawnCards: CardId[] } {
+  if (deck.cards.length < count) {
+    throw new Error(
+      `Cannot draw ${count} cards: only ${deck.cards.length} available in ${deck.config.id}`,
+    );
+  }
+
+  const drawnCards = deck.cards.slice(0, count);
+
+  const newDeck = produce(deck, (draft) => {
+    draft.cards.splice(0, count);
+  });
+
+  const newHand = produce(hand, (draft) => {
+    draft.cards.push(...drawnCards);
+  });
+
+  return {
+    fromZone: newDeck,
+    toZone: newHand,
+    drawnCards,
+  };
+}
+
+/**
+ * Shuffles a zone using seeded RNG for deterministic replay
+ * @param zone - Zone to shuffle
+ * @param seed - Random seed for determinism
+ * @returns Updated zone with shuffled cards
+ */
+export function shuffle(zone: Zone, seed: string): Zone {
+  const rng = seedrandom(seed);
+
+  return produce(zone, (draft) => {
+    // Fisher-Yates shuffle with seeded RNG
+    for (let i = draft.cards.length - 1; i > 0; i--) {
+      const j = Math.floor(rng() * (i + 1));
+      const cardI = draft.cards[i];
+      const cardJ = draft.cards[j];
+      if (cardI !== undefined && cardJ !== undefined) {
+        draft.cards[i] = cardJ;
+        draft.cards[j] = cardI;
+      }
+    }
+  });
+}
+
+/**
+ * Searches a zone for cards matching a filter
+ * @param zone - Zone to search
+ * @param filter - Filter function
+ * @returns Array of matching card IDs
+ */
+export function search(
+  zone: Zone,
+  filter: (cardId: CardId) => boolean,
+): CardId[] {
+  return zone.cards.filter(filter);
+}
+
+/**
+ * Peeks at the top N cards of a zone without removing them
+ * @param zone - Zone to peek at
+ * @param count - Number of cards to peek
+ * @returns Array of card IDs
+ */
+export function peek(zone: Zone, count: number): CardId[] {
+  return zone.cards.slice(0, count);
+}
+
+/**
+ * Mills cards from deck to graveyard
+ * @param deck - Source deck zone
+ * @param graveyard - Destination graveyard zone
+ * @param count - Number of cards to mill
+ * @returns Updated zones and milled cards
+ */
+export function mill(
+  deck: Zone,
+  graveyard: Zone,
+  count: number,
+): { fromZone: Zone; toZone: Zone; milledCards: CardId[] } {
+  const milledCards = deck.cards.slice(0, count);
+
+  const newDeck = produce(deck, (draft) => {
+    draft.cards.splice(0, count);
+  });
+
+  const newGraveyard = produce(graveyard, (draft) => {
+    draft.cards.push(...milledCards);
+  });
+
+  return {
+    fromZone: newDeck,
+    toZone: newGraveyard,
+    milledCards,
+  };
+}
+
+/**
+ * Reveals cards (makes them temporarily visible)
+ * @param cardIds - Cards to reveal
+ * @returns Array of revealed card IDs
+ */
+export function reveal(cardIds: CardId[]): CardId[] {
+  return [...cardIds];
+}
+
+/**
+ * Gets the number of cards in a zone
+ * @param zone - Zone to query
+ * @returns Number of cards
+ */
+export function getZoneSize(zone: Zone): number {
+  return zone.cards.length;
+}
+
+/**
+ * Gets all cards in a zone
+ * @param zone - Zone to query
+ * @returns Array of card IDs
+ */
+export function getCardsInZone(zone: Zone): CardId[] {
+  return [...zone.cards];
+}
+
+/**
+ * Gets the top card of a zone
+ * @param zone - Zone to query
+ * @returns Top card ID or undefined if empty
+ */
+export function getTopCard(zone: Zone): CardId | undefined {
+  return zone.cards[0];
+}
+
+/**
+ * Gets the bottom card of a zone
+ * @param zone - Zone to query
+ * @returns Bottom card ID or undefined if empty
+ */
+export function getBottomCard(zone: Zone): CardId | undefined {
+  return zone.cards[zone.cards.length - 1];
+}
+
+/**
+ * Checks if a card is in a zone
+ * @param zone - Zone to check
+ * @param cardId - Card to look for
+ * @returns True if card is in zone
+ */
+export function isCardInZone(zone: Zone, cardId: CardId): boolean {
+  return zone.cards.includes(cardId);
+}
+
+/**
+ * Adds a card to the top of a zone
+ * @param zone - Target zone
+ * @param cardId - Card to add
+ * @returns Updated zone
+ * @throws Error if zone is at maximum size
+ */
+export function addCardToTop(zone: Zone, cardId: CardId): Zone {
+  if (
+    zone.config.maxSize !== undefined &&
+    zone.cards.length >= zone.config.maxSize
+  ) {
+    throw new Error(
+      `Cannot add card: zone is at maximum size (${zone.config.maxSize})`,
+    );
+  }
+
+  return produce(zone, (draft) => {
+    draft.cards.unshift(cardId);
+  });
+}
+
+/**
+ * Adds a card to the bottom of a zone
+ * @param zone - Target zone
+ * @param cardId - Card to add
+ * @returns Updated zone
+ * @throws Error if zone is at maximum size
+ */
+export function addCardToBottom(zone: Zone, cardId: CardId): Zone {
+  if (
+    zone.config.maxSize !== undefined &&
+    zone.cards.length >= zone.config.maxSize
+  ) {
+    throw new Error(
+      `Cannot add card: zone is at maximum size (${zone.config.maxSize})`,
+    );
+  }
+
+  return produce(zone, (draft) => {
+    draft.cards.push(cardId);
+  });
+}
+
+/**
+ * Clears all cards from a zone
+ * @param zone - Zone to clear
+ * @returns Updated zone with no cards
+ */
+export function clearZone(zone: Zone): Zone {
+  return produce(zone, (draft) => {
+    draft.cards = [];
+  });
+}
+
+/**
+ * Finds the first zone containing a card
+ * @param cardId - Card to find
+ * @param zones - Zones to search
+ * @returns First zone containing the card, or undefined if not found
+ */
+export function findCardInZones(
+  cardId: CardId,
+  zones: Zone[],
+): Zone | undefined {
+  return zones.find((zone) => isCardInZone(zone, cardId));
+}

package/src/zones/zone-state-helpers.test.ts

@@ -0,0 +1,337 @@
+import { describe, expect, it } from "bun:test";
+import { createCardId, createPlayerId, createZoneId } from "../types";
+import { createZone } from "./zone-factory";
+import {
+  createPlayerZones,
+  getCardZone,
+  moveCardInState,
+} from "./zone-state-helpers";
+
+describe("Zone State Helpers", () => {
+  describe("createPlayerZones", () => {
+    it("should create zones for each player with factory", () => {
+      const p1 = createPlayerId("p1");
+      const p2 = createPlayerId("p2");
+      const players = [p1, p2];
+
+      const zones = createPlayerZones(players, () => [] as string[]);
+
+      expect(zones[p1]).toBeDefined();
+      expect(zones[p2]).toBeDefined();
+      expect(Object.keys(zones)).toHaveLength(2);
+    });
+
+    it("should initialize with default values", () => {
+      const p1 = createPlayerId("p1");
+      const p2 = createPlayerId("p2");
+      const players = [p1, p2];
+
+      const zones = createPlayerZones(players, () => []);
+
+      expect(zones[p1]).toEqual([]);
+      expect(zones[p2]).toEqual([]);
+    });
+
+    it("should initialize with custom factory function", () => {
+      const p1 = createPlayerId("p1");
+      const p2 = createPlayerId("p2");
+      const players = [p1, p2];
+
+      const zones = createPlayerZones(players, () => ({ count: 0 }));
+
+      expect(zones[p1]).toEqual({ count: 0 });
+      expect(zones[p2]).toEqual({ count: 0 });
+    });
+
+    it("should call factory function for each player", () => {
+      const players = [createPlayerId("p1"), createPlayerId("p2")];
+      let callCount = 0;
+
+      createPlayerZones(players, () => {
+        callCount++;
+        return [];
+      });
+
+      expect(callCount).toBe(2);
+    });
+
+    it("should handle single player", () => {
+      const p1 = createPlayerId("p1");
+      const players = [p1];
+
+      const zones = createPlayerZones(players, () => [] as string[]);
+
+      expect(Object.keys(zones)).toHaveLength(1);
+      expect(zones[p1]).toBeDefined();
+    });
+
+    it("should handle empty players array", () => {
+      const players: ReturnType<typeof createPlayerId>[] = [];
+
+      const zones = createPlayerZones(players, () => [] as string[]);
+
+      expect(Object.keys(zones)).toHaveLength(0);
+    });
+  });
+
+  describe("moveCardInState", () => {
+    it("should move card between zones in flat state", () => {
+      const _playerId = createPlayerId("p1");
+      const cardId = createCardId("card-1");
+
+      const state = {
+        hand: createZone(
+          {
+            id: createZoneId("hand"),
+            name: "Hand",
+            visibility: "private",
+            ordered: false,
+          },
+          [cardId, createCardId("card-2")],
+        ),
+        deck: createZone({
+          id: createZoneId("deck"),
+          name: "Deck",
+          visibility: "secret",
+          ordered: true,
+        }),
+      };
+
+      const newState = moveCardInState(state, "hand", "deck", cardId);
+
+      expect(newState.hand.cards).not.toContain(cardId);
+      expect(newState.hand.cards).toHaveLength(1);
+      expect(newState.deck.cards).toContain(cardId);
+      expect(newState.deck.cards).toHaveLength(1);
+    });
+
+    it("should preserve other zones in state", () => {
+      const cardId = createCardId("card-1");
+
+      const state = {
+        hand: createZone(
+          {
+            id: createZoneId("hand"),
+            name: "Hand",
+            visibility: "private",
+            ordered: false,
+          },
+          [cardId],
+        ),
+        deck: createZone({
+          id: createZoneId("deck"),
+          name: "Deck",
+          visibility: "secret",
+          ordered: true,
+        }),
+        graveyard: createZone(
+          {
+            id: createZoneId("graveyard"),
+            name: "Graveyard",
+            visibility: "public",
+            ordered: true,
+          },
+          [createCardId("card-3")],
+        ),
+      };
+
+      const newState = moveCardInState(state, "hand", "deck", cardId);
+
+      expect(newState.graveyard).toBe(state.graveyard);
+      expect(newState.graveyard.cards).toHaveLength(1);
+    });
+
+    it("should maintain immutability", () => {
+      const cardId = createCardId("card-1");
+
+      const state = {
+        hand: createZone(
+          {
+            id: createZoneId("hand"),
+            name: "Hand",
+            visibility: "private",
+            ordered: false,
+          },
+          [cardId],
+        ),
+        deck: createZone({
+          id: createZoneId("deck"),
+          name: "Deck",
+          visibility: "secret",
+          ordered: true,
+        }),
+      };
+
+      const originalHandCards = state.hand.cards;
+      const originalDeckCards = state.deck.cards;
+
+      const newState = moveCardInState(state, "hand", "deck", cardId);
+
+      expect(state.hand.cards).toBe(originalHandCards);
+      expect(state.deck.cards).toBe(originalDeckCards);
+      expect(newState.hand).not.toBe(state.hand);
+      expect(newState.deck).not.toBe(state.deck);
+    });
+
+    it("should add card with optional position", () => {
+      const cardId = createCardId("card-1");
+
+      const state = {
+        hand: createZone(
+          {
+            id: createZoneId("hand"),
+            name: "Hand",
+            visibility: "private",
+            ordered: false,
+          },
+          [cardId],
+        ),
+        deck: createZone(
+          {
+            id: createZoneId("deck"),
+            name: "Deck",
+            visibility: "secret",
+            ordered: true,
+          },
+          [createCardId("card-2")],
+        ),
+      };
+
+      const newState = moveCardInState(state, "hand", "deck", cardId, 0);
+
+      expect(newState.deck.cards[0]).toBe(cardId);
+      expect(newState.deck.cards[1]).toBe(createCardId("card-2"));
+    });
+  });
+
+  describe("getCardZone", () => {
+    it("should find card in first zone", () => {
+      const cardId = createCardId("card-1");
+
+      const state = {
+        hand: createZone(
+          {
+            id: createZoneId("hand"),
+            name: "Hand",
+            visibility: "private",
+            ordered: false,
+          },
+          [cardId, createCardId("card-2")],
+        ),
+        deck: createZone({
+          id: createZoneId("deck"),
+          name: "Deck",
+          visibility: "secret",
+          ordered: true,
+        }),
+      };
+
+      const zoneName = getCardZone(state, cardId);
+
+      expect(zoneName).toBe("hand");
+    });
+
+    it("should find card in later zone", () => {
+      const cardId = createCardId("card-3");
+
+      const state = {
+        hand: createZone(
+          {
+            id: createZoneId("hand"),
+            name: "Hand",
+            visibility: "private",
+            ordered: false,
+          },
+          [createCardId("card-1")],
+        ),
+        deck: createZone(
+          {
+            id: createZoneId("deck"),
+            name: "Deck",
+            visibility: "secret",
+            ordered: true,
+          },
+          [createCardId("card-2"), cardId],
+        ),
+      };
+
+      const zoneName = getCardZone(state, cardId);
+
+      expect(zoneName).toBe("deck");
+    });
+
+    it("should return undefined when card not found", () => {
+      const state = {
+        hand: createZone(
+          {
+            id: createZoneId("hand"),
+            name: "Hand",
+            visibility: "private",
+            ordered: false,
+          },
+          [createCardId("card-1")],
+        ),
+        deck: createZone({
+          id: createZoneId("deck"),
+          name: "Deck",
+          visibility: "secret",
+          ordered: true,
+        }),
+      };
+
+      const zoneName = getCardZone(state, createCardId("missing"));
+
+      expect(zoneName).toBeUndefined();
+    });
+
+    it("should return first zone if card in multiple zones", () => {
+      const cardId = createCardId("card-1");
+
+      const state = {
+        hand: createZone(
+          {
+            id: createZoneId("hand"),
+            name: "Hand",
+            visibility: "private",
+            ordered: false,
+          },
+          [cardId],
+        ),
+        deck: createZone(
+          {
+            id: createZoneId("deck"),
+            name: "Deck",
+            visibility: "secret",
+            ordered: true,
+          },
+          [cardId],
+        ),
+      };
+
+      const zoneName = getCardZone(state, cardId);
+
+      expect(zoneName).toBe("hand");
+    });
+
+    it("should handle empty zones", () => {
+      const state = {
+        hand: createZone({
+          id: createZoneId("hand"),
+          name: "Hand",
+          visibility: "private",
+          ordered: false,
+        }),
+        deck: createZone({
+          id: createZoneId("deck"),
+          name: "Deck",
+          visibility: "secret",
+          ordered: true,
+        }),
+      };
+
+      const zoneName = getCardZone(state, createCardId("card-1"));
+
+      expect(zoneName).toBeUndefined();
+    });
+  });
+});