@drmxrcy/tcg-core 0.0.0-202602060542

package/src/operations/zone-operations.test.ts

@@ -0,0 +1,295 @@
+import { describe, expect, it } from "bun:test";
+import type { CardId, PlayerId, ZoneId } from "../types";
+import type { ZoneOperations } from "./zone-operations";
+
+describe("ZoneOperations Interface", () => {
+  // Mock implementation for testing the interface structure
+  const createMockZoneOperations = (): ZoneOperations => {
+    const zones: Record<string, { cardIds: string[] }> = {
+      deck: { cardIds: ["card-1", "card-2", "card-3"] },
+      hand: { cardIds: ["card-4"] },
+      play: { cardIds: [] },
+    };
+
+    return {
+      moveCard: (args) => {
+        const { cardId, targetZoneId } = args;
+        // Find and remove from source
+        for (const zoneId in zones) {
+          const index = zones[zoneId].cardIds.indexOf(cardId);
+          if (index !== -1) {
+            zones[zoneId].cardIds.splice(index, 1);
+            break;
+          }
+        }
+        // Add to target
+        if (!zones[targetZoneId]) {
+          zones[targetZoneId] = { cardIds: [] };
+        }
+        if (args.position === "top") {
+          zones[targetZoneId].cardIds.unshift(cardId);
+        } else if (args.position === "bottom" || args.position === undefined) {
+          zones[targetZoneId].cardIds.push(cardId);
+        } else if (typeof args.position === "number") {
+          zones[targetZoneId].cardIds.splice(args.position, 0, cardId);
+        }
+      },
+
+      getCardsInZone: (zoneId, ownerId?) => {
+        // Return a copy to avoid mutation issues
+        return [...(zones[zoneId]?.cardIds || [])] as unknown as CardId[];
+      },
+
+      shuffleZone: (zoneId, ownerId?) => {
+        // Mock shuffle - just reverse for testing
+        if (zones[zoneId]) {
+          zones[zoneId].cardIds.reverse();
+        }
+      },
+
+      getCardZone: (cardId) => {
+        for (const zoneId in zones) {
+          if (zones[zoneId].cardIds.includes(cardId)) {
+            return zoneId as ZoneId;
+          }
+        }
+        return undefined;
+      },
+
+      drawCards: (params) => {
+        const { from, to, count, playerId } = params;
+        const drawn: CardId[] = [];
+        const sourceZone = zones[from];
+        if (sourceZone) {
+          for (let i = 0; i < count; i++) {
+            const cardId = sourceZone.cardIds.shift();
+            if (cardId) {
+              drawn.push(cardId as CardId);
+              if (!zones[to]) zones[to] = { cardIds: [] };
+              zones[to].cardIds.push(cardId);
+            }
+          }
+        }
+        return drawn;
+      },
+
+      mulligan: (params) => {
+        const { hand, deck, drawCount, playerId } = params;
+        // Move all cards from hand to deck
+        if (zones[hand]) {
+          zones[deck].cardIds.push(...zones[hand].cardIds);
+          zones[hand].cardIds = [];
+        }
+        // Shuffle (reverse for testing)
+        zones[deck].cardIds.reverse();
+        // Draw new cards
+        for (let i = 0; i < drawCount; i++) {
+          const cardId = zones[deck].cardIds.shift();
+          if (cardId) {
+            zones[hand].cardIds.push(cardId);
+          }
+        }
+      },
+
+      bulkMove: (params) => {
+        const { from, to, count, playerId, position } = params;
+        const moved: CardId[] = [];
+        const sourceZone = zones[from];
+        if (sourceZone) {
+          for (let i = 0; i < count; i++) {
+            const cardId = sourceZone.cardIds.shift();
+            if (cardId) {
+              moved.push(cardId as CardId);
+              if (!zones[to]) zones[to] = { cardIds: [] };
+              if (position === "top") {
+                zones[to].cardIds.unshift(cardId);
+              } else {
+                zones[to].cardIds.push(cardId);
+              }
+            }
+          }
+        }
+        return moved;
+      },
+
+      createDeck: (params) => {
+        const { zoneId, playerId, cardCount, shuffle } = params;
+        const created: CardId[] = [];
+        if (!zones[zoneId]) zones[zoneId] = { cardIds: [] };
+        for (let i = 0; i < cardCount; i++) {
+          const cardId = `card-${Date.now()}-${i}` as CardId;
+          created.push(cardId);
+          zones[zoneId].cardIds.push(cardId);
+        }
+        if (shuffle) {
+          zones[zoneId].cardIds.reverse(); // Mock shuffle
+        }
+        return created;
+      },
+    };
+  };
+
+  describe("moveCard", () => {
+    it("should move a card to target zone", () => {
+      const ops = createMockZoneOperations();
+
+      ops.moveCard({
+        cardId: "card-1" as CardId,
+        targetZoneId: "hand" as ZoneId,
+      });
+
+      const deckCards = ops.getCardsInZone("deck" as ZoneId);
+      const handCards = ops.getCardsInZone("hand" as ZoneId);
+
+      expect(deckCards).not.toContain("card-1");
+      expect(handCards).toContain("card-1");
+    });
+
+    it("should add card to top when position is 'top'", () => {
+      const ops = createMockZoneOperations();
+
+      ops.moveCard({
+        cardId: "card-1" as CardId,
+        targetZoneId: "hand" as ZoneId,
+        position: "top",
+      });
+
+      const handCards = ops.getCardsInZone("hand" as ZoneId);
+      expect(handCards[0]).toBe("card-1" as unknown as CardId);
+    });
+
+    it("should add card to bottom when position is 'bottom'", () => {
+      const ops = createMockZoneOperations();
+
+      ops.moveCard({
+        cardId: "card-1" as CardId,
+        targetZoneId: "hand" as ZoneId,
+        position: "bottom",
+      });
+
+      const handCards = ops.getCardsInZone("hand" as ZoneId);
+      expect(handCards[handCards.length - 1]).toBe(
+        "card-1" as unknown as CardId,
+      );
+    });
+
+    it("should insert card at specific position when position is a number", () => {
+      const ops = createMockZoneOperations();
+
+      ops.moveCard({
+        cardId: "card-4" as CardId,
+        targetZoneId: "deck" as ZoneId,
+        position: 1,
+      });
+
+      const deckCards = ops.getCardsInZone("deck" as ZoneId);
+      expect(deckCards[1]).toBe("card-4" as unknown as CardId);
+    });
+  });
+
+  describe("getCardsInZone", () => {
+    it("should return all cards in a zone", () => {
+      const ops = createMockZoneOperations();
+
+      const deckCards = ops.getCardsInZone("deck" as ZoneId);
+
+      expect(deckCards).toHaveLength(3);
+      expect(deckCards).toContain("card-1");
+      expect(deckCards).toContain("card-2");
+      expect(deckCards).toContain("card-3");
+    });
+
+    it("should return empty array for empty zone", () => {
+      const ops = createMockZoneOperations();
+
+      const playCards = ops.getCardsInZone("play" as ZoneId);
+
+      expect(playCards).toHaveLength(0);
+    });
+
+    it("should accept optional ownerId parameter for player-specific zones", () => {
+      const ops = createMockZoneOperations();
+
+      // This just tests the signature works
+      const cards = ops.getCardsInZone(
+        "hand" as ZoneId,
+        "player-1" as unknown as PlayerId,
+      );
+
+      expect(cards).toBeDefined();
+    });
+  });
+
+  describe("shuffleZone", () => {
+    it("should shuffle cards in a zone", () => {
+      const ops = createMockZoneOperations();
+
+      const beforeShuffle = ops.getCardsInZone("deck" as ZoneId);
+      ops.shuffleZone("deck" as ZoneId);
+      const afterShuffle = ops.getCardsInZone("deck" as ZoneId);
+
+      // Mock implementation reverses, so order should be different
+      expect(afterShuffle).toHaveLength(beforeShuffle.length);
+      expect(afterShuffle[0]).not.toBe(beforeShuffle[0]);
+    });
+
+    it("should accept optional ownerId parameter for player-specific zones", () => {
+      const ops = createMockZoneOperations();
+
+      // This just tests the signature works
+      ops.shuffleZone("deck" as ZoneId, "player-1" as unknown as PlayerId);
+
+      expect(true).toBe(true); // Just verify it doesn't throw
+    });
+  });
+
+  describe("getCardZone", () => {
+    it("should return the zone containing a card", () => {
+      const ops = createMockZoneOperations();
+
+      const zone = ops.getCardZone("card-2" as CardId);
+
+      expect(zone).toBe("deck" as ZoneId);
+    });
+
+    it("should return undefined when card is not in any zone", () => {
+      const ops = createMockZoneOperations();
+
+      const zone = ops.getCardZone("nonexistent-card" as CardId);
+
+      expect(zone).toBeUndefined();
+    });
+  });
+
+  describe("Type Safety", () => {
+    it("should enforce CardId type for card identifiers", () => {
+      const ops = createMockZoneOperations();
+
+      // This is a compile-time test - it should type-check correctly
+      const zone = ops.getCardZone("card-1" as unknown as CardId);
+
+      expect(zone).toBeDefined();
+    });
+
+    it("should enforce ZoneId type for zone identifiers", () => {
+      const ops = createMockZoneOperations();
+
+      // This is a compile-time test - it should type-check correctly
+      const cards = ops.getCardsInZone("deck" as unknown as ZoneId);
+
+      expect(cards).toBeDefined();
+    });
+
+    it("should enforce PlayerId type for owner identifiers", () => {
+      const ops = createMockZoneOperations();
+
+      // This is a compile-time test - it should type-check correctly
+      const cards = ops.getCardsInZone(
+        "hand" as unknown as ZoneId,
+        "player-1" as unknown as PlayerId,
+      );
+
+      expect(cards).toBeDefined();
+    });
+  });
+});

package/src/operations/zone-operations.ts

@@ -0,0 +1,223 @@
+import type { CardId, PlayerId, ZoneId } from "../types";
+
+/**
+ * Zone Operations Interface
+ *
+ * Provides API for manipulating cards between zones without directly mutating internal state.
+ * These operations are the only way for moves to interact with the framework's zone management.
+ *
+ * All zone operations maintain consistency:
+ * - Cards can only be in one zone at a time
+ * - Moving a card automatically removes it from its current zone
+ * - Zone order is preserved for ordered zones (like decks)
+ */
+export interface ZoneOperations {
+  /**
+   * Move a card from its current zone to a target zone
+   *
+   * @param args - Move card arguments
+   * @param args.cardId - ID of the card to move
+   * @param args.targetZoneId - ID of the zone to move the card to
+   * @param args.position - Where to place the card in the target zone:
+   *   - 'top': Add to the beginning (index 0)
+   *   - 'bottom': Add to the end (default)
+   *   - number: Insert at specific index
+   *
+   * @example
+   * ```typescript
+   * // Draw a card (deck -> hand)
+   * zones.moveCard({
+   *   cardId: 'card-1',
+   *   targetZoneId: 'hand',
+   *   position: 'bottom'
+   * });
+   *
+   * // Put card on top of deck
+   * zones.moveCard({
+   *   cardId: 'card-2',
+   *   targetZoneId: 'deck',
+   *   position: 'top'
+   * });
+   * ```
+   */
+  moveCard(args: {
+    cardId: CardId;
+    targetZoneId: ZoneId;
+    position?: "top" | "bottom" | number;
+  }): void;
+
+  /**
+   * Get all cards in a zone
+   *
+   * @param zoneId - ID of the zone to query
+   * @param ownerId - Optional player ID to filter by owner (for player-specific zones)
+   * @returns Array of card IDs in the zone (in order for ordered zones)
+   *
+   * @example
+   * ```typescript
+   * // Get all cards in a player's hand
+   * const handCards = zones.getCardsInZone('hand', 'player-1');
+   *
+   * // Get all cards in shared play area
+   * const playCards = zones.getCardsInZone('play');
+   * ```
+   */
+  getCardsInZone(zoneId: ZoneId, ownerId?: PlayerId): CardId[];
+
+  /**
+   * Shuffle cards in a zone
+   *
+   * @param zoneId - ID of the zone to shuffle
+   * @param ownerId - Optional player ID for player-specific zones
+   *
+   * @example
+   * ```typescript
+   * // Shuffle a player's deck
+   * zones.shuffleZone('deck', 'player-1');
+   * ```
+   */
+  shuffleZone(zoneId: ZoneId, ownerId?: PlayerId): void;
+
+  /**
+   * Get the zone containing a card
+   *
+   * @param cardId - ID of the card to find
+   * @returns Zone ID if card is in a zone, undefined otherwise
+   *
+   * @example
+   * ```typescript
+   * const zone = zones.getCardZone('card-1');
+   * if (zone === 'hand') {
+   *   // Card is in hand
+   * }
+   * ```
+   */
+  getCardZone(cardId: CardId): ZoneId | undefined;
+
+  /**
+   * Draw cards from one zone to another
+   *
+   * High-level utility that moves multiple cards from source to target zone.
+   * Commonly used for drawing cards from deck to hand.
+   *
+   * @param params - Draw parameters
+   * @param params.from - Source zone ID (e.g., 'deck')
+   * @param params.to - Target zone ID (e.g., 'hand')
+   * @param params.count - Number of cards to draw
+   * @param params.playerId - Player ID for player-specific zones
+   * @returns Array of card IDs that were drawn
+   *
+   * @example
+   * ```typescript
+   * // Draw 5 cards from deck to hand
+   * const drawnCards = zones.drawCards({
+   *   from: 'deck',
+   *   to: 'hand',
+   *   count: 5,
+   *   playerId: 'player-1'
+   * });
+   * ```
+   */
+  drawCards(params: {
+    from: ZoneId;
+    to: ZoneId;
+    count: number;
+    playerId: PlayerId;
+  }): CardId[];
+
+  /**
+   * Perform mulligan - shuffle hand back into deck and redraw
+   *
+   * High-level utility for standard mulligan operation:
+   * 1. Move all cards from hand to deck
+   * 2. Shuffle deck
+   * 3. Draw the specified number of cards
+   *
+   * @param params - Mulligan parameters
+   * @param params.hand - Hand zone ID
+   * @param params.deck - Deck zone ID
+   * @param params.drawCount - Number of cards to draw after shuffle
+   * @param params.playerId - Player ID
+   *
+   * @example
+   * ```typescript
+   * // Mulligan: shuffle hand back and draw 7 new cards
+   * zones.mulligan({
+   *   hand: 'hand',
+   *   deck: 'deck',
+   *   drawCount: 7,
+   *   playerId: 'player-1'
+   * });
+   * ```
+   */
+  mulligan(params: {
+    hand: ZoneId;
+    deck: ZoneId;
+    drawCount: number;
+    playerId: PlayerId;
+  }): void;
+
+  /**
+   * Move multiple cards in bulk
+   *
+   * High-level utility for moving many cards at once.
+   * Commonly used for setup operations like placing shields.
+   *
+   * @param params - Bulk move parameters
+   * @param params.from - Source zone ID
+   * @param params.to - Target zone ID
+   * @param params.count - Number of cards to move
+   * @param params.playerId - Player ID
+   * @param params.position - Where to place cards ('top' or 'bottom', default 'bottom')
+   * @returns Array of card IDs that were moved
+   *
+   * @example
+   * ```typescript
+   * // Move 6 cards from deck to shields
+   * zones.bulkMove({
+   *   from: 'deck',
+   *   to: 'shieldSection',
+   *   count: 6,
+   *   playerId: 'player-1'
+   * });
+   * ```
+   */
+  bulkMove(params: {
+    from: ZoneId;
+    to: ZoneId;
+    count: number;
+    playerId: PlayerId;
+    position?: "top" | "bottom";
+  }): CardId[];
+
+  /**
+   * Create a deck with placeholder cards
+   *
+   * High-level utility for game setup. Creates card instances and
+   * places them in the specified zone.
+   *
+   * @param params - Deck creation parameters
+   * @param params.zoneId - Zone to place the cards in
+   * @param params.playerId - Owner of the cards
+   * @param params.cardCount - Number of cards to create
+   * @param params.shuffle - Whether to shuffle after creation (default false)
+   * @returns Array of created card IDs
+   *
+   * @example
+   * ```typescript
+   * // Create and shuffle a 50-card deck
+   * zones.createDeck({
+   *   zoneId: 'deck',
+   *   playerId: 'player-1',
+   *   cardCount: 50,
+   *   shuffle: true
+   * });
+   * ```
+   */
+  createDeck(params: {
+    zoneId: ZoneId;
+    playerId: PlayerId;
+    cardCount: number;
+    shuffle?: boolean;
+  }): CardId[];
+}