@drmxrcy/tcg-core 0.0.0-202602060542

package/src/testing/test-zone-factory.test.ts

@@ -0,0 +1,295 @@
+import { describe, expect, it } from "bun:test";
+import { createCardId, createPlayerId } from "../types";
+import type { Zone } from "../zones/zone";
+import {
+  createTestDeck,
+  createTestGraveyard,
+  createTestHand,
+  createTestPlayArea,
+  createTestZone,
+} from "./test-zone-factory";
+
+describe("test-zone-factory", () => {
+  describe("createTestZone", () => {
+    it("should create zone with default values", () => {
+      const zone = createTestZone();
+
+      expect(zone.config.id).toBeDefined();
+      expect(zone.config.name).toBeDefined();
+      expect(zone.config.visibility).toBeDefined();
+      expect(zone.config.ordered).toBeDefined();
+      expect(zone.cards).toEqual([]);
+    });
+
+    it("should override config properties", () => {
+      const zone = createTestZone({
+        name: "Custom Zone",
+        visibility: "secret",
+        ordered: true,
+      });
+
+      expect(zone.config.name).toBe("Custom Zone");
+      expect(zone.config.visibility).toBe("secret");
+      expect(zone.config.ordered).toBe(true);
+    });
+
+    it("should include initial cards", () => {
+      const cards = [
+        createCardId("card1"),
+        createCardId("card2"),
+        createCardId("card3"),
+      ];
+
+      const zone = createTestZone({}, cards);
+
+      expect(zone.cards).toEqual(cards);
+      expect(zone.cards.length).toBe(3);
+    });
+
+    it("should generate unique zone IDs", () => {
+      const zone1 = createTestZone();
+      const zone2 = createTestZone();
+      const zone3 = createTestZone();
+
+      expect(zone1.config.id).not.toBe(zone2.config.id);
+      expect(zone2.config.id).not.toBe(zone3.config.id);
+    });
+
+    it("should support maxSize", () => {
+      const zone = createTestZone({ maxSize: 10 });
+
+      expect(zone.config.maxSize).toBe(10);
+    });
+
+    it("should support owner", () => {
+      const playerId = createPlayerId("p1");
+      const zone = createTestZone({ owner: playerId });
+
+      expect(zone.config.owner).toBe(playerId);
+    });
+
+    it("should support faceDown", () => {
+      const zone = createTestZone({ faceDown: true });
+
+      expect(zone.config.faceDown).toBe(true);
+    });
+
+    it("should create valid Zone type", () => {
+      const zone = createTestZone();
+
+      // TypeScript type check
+      const validate = (z: Zone) => z;
+      expect(() => validate(zone)).not.toThrow();
+    });
+  });
+
+  describe("createTestDeck", () => {
+    it("should create deck zone with appropriate defaults", () => {
+      const deck = createTestDeck();
+
+      expect(deck.config.name).toContain("Deck");
+      expect(deck.config.visibility).toBe("secret");
+      expect(deck.config.ordered).toBe(true);
+      expect(deck.config.faceDown).toBe(true);
+    });
+
+    it("should include cards when provided", () => {
+      const cards = [
+        createCardId("card1"),
+        createCardId("card2"),
+        createCardId("card3"),
+      ];
+
+      const deck = createTestDeck(cards);
+
+      expect(deck.cards).toEqual(cards);
+    });
+
+    it("should support owner", () => {
+      const playerId = createPlayerId("p1");
+      const deck = createTestDeck([], playerId);
+
+      expect(deck.config.owner).toBe(playerId);
+    });
+
+    it("should maintain card order", () => {
+      const cards = [
+        createCardId("card1"),
+        createCardId("card2"),
+        createCardId("card3"),
+      ];
+
+      const deck = createTestDeck(cards);
+
+      // Order should be preserved
+      expect(deck.cards[0]).toBe(cards[0]);
+      expect(deck.cards[1]).toBe(cards[1]);
+      expect(deck.cards[2]).toBe(cards[2]);
+    });
+  });
+
+  describe("createTestHand", () => {
+    it("should create hand zone with appropriate defaults", () => {
+      const hand = createTestHand();
+
+      expect(hand.config.name).toContain("Hand");
+      expect(hand.config.visibility).toBe("private");
+      expect(hand.config.ordered).toBe(false);
+      expect(hand.config.faceDown).toBe(false);
+    });
+
+    it("should include cards when provided", () => {
+      const cards = [createCardId("card1"), createCardId("card2")];
+
+      const hand = createTestHand(cards);
+
+      expect(hand.cards).toEqual(cards);
+    });
+
+    it("should support owner", () => {
+      const playerId = createPlayerId("p1");
+      const hand = createTestHand([], playerId);
+
+      expect(hand.config.owner).toBe(playerId);
+    });
+  });
+
+  describe("createTestPlayArea", () => {
+    it("should create play area with appropriate defaults", () => {
+      const playArea = createTestPlayArea();
+
+      expect(playArea.config.name).toContain("Play Area");
+      expect(playArea.config.visibility).toBe("public");
+      expect(playArea.config.ordered).toBe(false);
+      expect(playArea.config.faceDown).toBe(false);
+    });
+
+    it("should include cards when provided", () => {
+      const cards = [createCardId("card1"), createCardId("card2")];
+
+      const playArea = createTestPlayArea(cards);
+
+      expect(playArea.cards).toEqual(cards);
+    });
+
+    it("should support owner", () => {
+      const playerId = createPlayerId("p1");
+      const playArea = createTestPlayArea([], playerId);
+
+      expect(playArea.config.owner).toBe(playerId);
+    });
+  });
+
+  describe("createTestGraveyard", () => {
+    it("should create graveyard with appropriate defaults", () => {
+      const graveyard = createTestGraveyard();
+
+      expect(graveyard.config.name).toContain("Graveyard");
+      expect(graveyard.config.visibility).toBe("public");
+      expect(graveyard.config.ordered).toBe(true);
+      expect(graveyard.config.faceDown).toBe(false);
+    });
+
+    it("should include cards when provided", () => {
+      const cards = [createCardId("card1"), createCardId("card2")];
+
+      const graveyard = createTestGraveyard(cards);
+
+      expect(graveyard.cards).toEqual(cards);
+    });
+
+    it("should support owner", () => {
+      const playerId = createPlayerId("p1");
+      const graveyard = createTestGraveyard([], playerId);
+
+      expect(graveyard.config.owner).toBe(playerId);
+    });
+
+    it("should maintain card order", () => {
+      const cards = [
+        createCardId("card1"),
+        createCardId("card2"),
+        createCardId("card3"),
+      ];
+
+      const graveyard = createTestGraveyard(cards);
+
+      // Order should be preserved (cards go on top)
+      expect(graveyard.cards[0]).toBe(cards[0]);
+      expect(graveyard.cards[1]).toBe(cards[1]);
+      expect(graveyard.cards[2]).toBe(cards[2]);
+    });
+  });
+
+  describe("integration", () => {
+    it("should create complete player zone setup", () => {
+      const playerId = createPlayerId("p1");
+
+      // Create all zones for a player
+      const deckCards = [
+        createCardId("card1"),
+        createCardId("card2"),
+        createCardId("card3"),
+      ];
+      const handCards = [createCardId("card4"), createCardId("card5")];
+
+      const deck = createTestDeck(deckCards, playerId);
+      const hand = createTestHand(handCards, playerId);
+      const playArea = createTestPlayArea([], playerId);
+      const graveyard = createTestGraveyard([], playerId);
+
+      // Verify all zones created correctly
+      expect(deck.config.owner).toBe(playerId);
+      expect(hand.config.owner).toBe(playerId);
+      expect(playArea.config.owner).toBe(playerId);
+      expect(graveyard.config.owner).toBe(playerId);
+
+      // Verify zones have correct visibility
+      expect(deck.config.visibility).toBe("secret");
+      expect(hand.config.visibility).toBe("private");
+      expect(playArea.config.visibility).toBe("public");
+      expect(graveyard.config.visibility).toBe("public");
+
+      // Verify cards distributed correctly
+      expect(deck.cards.length).toBe(3);
+      expect(hand.cards.length).toBe(2);
+      expect(playArea.cards.length).toBe(0);
+      expect(graveyard.cards.length).toBe(0);
+    });
+
+    it("should work with zone operations", () => {
+      const deck = createTestDeck([
+        createCardId("card1"),
+        createCardId("card2"),
+        createCardId("card3"),
+      ]);
+
+      // Test that zone factory creates zones compatible with zone operations
+      expect(deck.cards.length).toBe(3);
+      expect(deck.config.ordered).toBe(true);
+
+      // Simulate drawing a card
+      const drawnCard = deck.cards.pop();
+      expect(drawnCard).toBe(createCardId("card3"));
+      expect(deck.cards.length).toBe(2);
+    });
+
+    it("should create zones for multiple players", () => {
+      const p1 = createPlayerId("p1");
+      const p2 = createPlayerId("p2");
+
+      const p1Deck = createTestDeck(
+        [createCardId("p1-card1"), createCardId("p1-card2")],
+        p1,
+      );
+      const p2Deck = createTestDeck(
+        [createCardId("p2-card1"), createCardId("p2-card2")],
+        p2,
+      );
+
+      expect(p1Deck.config.owner).toBe(p1);
+      expect(p2Deck.config.owner).toBe(p2);
+      expect(p1Deck.config.id).not.toBe(p2Deck.config.id);
+    });
+  });
+});

package/src/testing/test-zone-factory.ts

@@ -0,0 +1,224 @@
+import type { CardId, PlayerId } from "../types";
+import { createZoneId } from "../types";
+import type { CardZoneConfig, Zone } from "../zones/zone";
+
+/**
+ * Test Zone Factory
+ *
+ * Factory functions for creating test zones
+ */
+
+let zoneCounter = 0;
+
+/**
+ * Create a test zone with optional configuration and cards
+ *
+ * Generates a zone with sensible defaults that can be customized.
+ * Each zone gets a unique ID automatically.
+ *
+ * @param configOverrides - Optional config properties to override
+ * @param cards - Optional initial cards
+ * @returns Zone for testing
+ *
+ * @example
+ * ```typescript
+ * // Create default zone
+ * const zone = createTestZone();
+ *
+ * // Create zone with cards
+ * const deck = createTestZone(
+ *   { name: 'Deck', visibility: 'secret', ordered: true },
+ *   ['card1', 'card2', 'card3']
+ * );
+ *
+ * // Create player-owned zone
+ * const hand = createTestZone({
+ *   name: 'Hand',
+ *   owner: 'player1',
+ *   visibility: 'private'
+ * });
+ * ```
+ */
+export function createTestZone(
+  configOverrides?: Partial<CardZoneConfig>,
+  cards: CardId[] = [],
+): Zone {
+  const id = createZoneId(`test-zone-${zoneCounter++}`);
+
+  const config: CardZoneConfig = {
+    id,
+    name: `Test Zone ${zoneCounter}`,
+    visibility: "public",
+    ordered: false,
+    ...configOverrides,
+  };
+
+  return {
+    config,
+    cards: [...cards],
+  };
+}
+
+/**
+ * Create a test deck zone
+ *
+ * Creates a zone with typical deck properties:
+ * - Secret visibility (no one can see cards)
+ * - Ordered (card order matters)
+ * - Face down
+ *
+ * @param cards - Optional initial cards
+ * @param owner - Optional owner player ID
+ * @returns Deck zone
+ *
+ * @example
+ * ```typescript
+ * const deck = createTestDeck(
+ *   ['card1', 'card2', 'card3'],
+ *   'player1'
+ * );
+ * ```
+ */
+export function createTestDeck(cards: CardId[] = [], owner?: PlayerId): Zone {
+  const id = createZoneId(`test-deck-${zoneCounter++}`);
+
+  return {
+    config: {
+      id,
+      name: owner ? `${owner} Deck` : "Test Deck",
+      visibility: "secret",
+      ordered: true,
+      faceDown: true,
+      owner,
+    },
+    cards: [...cards],
+  };
+}
+
+/**
+ * Create a test hand zone
+ *
+ * Creates a zone with typical hand properties:
+ * - Private visibility (owner can see, opponents cannot)
+ * - Unordered (card order doesn't matter)
+ * - Face up
+ *
+ * @param cards - Optional initial cards
+ * @param owner - Optional owner player ID
+ * @returns Hand zone
+ *
+ * @example
+ * ```typescript
+ * const hand = createTestHand(
+ *   ['card1', 'card2'],
+ *   'player1'
+ * );
+ * ```
+ */
+export function createTestHand(cards: CardId[] = [], owner?: PlayerId): Zone {
+  const id = createZoneId(`test-hand-${zoneCounter++}`);
+
+  return {
+    config: {
+      id,
+      name: owner ? `${owner} Hand` : "Test Hand",
+      visibility: "private",
+      ordered: false,
+      faceDown: false,
+      owner,
+    },
+    cards: [...cards],
+  };
+}
+
+/**
+ * Create a test play area zone
+ *
+ * Creates a zone with typical play area properties:
+ * - Public visibility (everyone can see)
+ * - Unordered (card order doesn't matter)
+ * - Face up
+ *
+ * @param cards - Optional initial cards
+ * @param owner - Optional owner player ID
+ * @returns Play area zone
+ *
+ * @example
+ * ```typescript
+ * const playArea = createTestPlayArea(
+ *   ['creature1', 'creature2'],
+ *   'player1'
+ * );
+ * ```
+ */
+export function createTestPlayArea(
+  cards: CardId[] = [],
+  owner?: PlayerId,
+): Zone {
+  const id = createZoneId(`test-play-area-${zoneCounter++}`);
+
+  return {
+    config: {
+      id,
+      name: owner ? `${owner} Play Area` : "Test Play Area",
+      visibility: "public",
+      ordered: false,
+      faceDown: false,
+      owner,
+    },
+    cards: [...cards],
+  };
+}
+
+/**
+ * Create a test graveyard zone
+ *
+ * Creates a zone with typical graveyard properties:
+ * - Public visibility (everyone can see)
+ * - Ordered (card order matters - cards go on top)
+ * - Face up
+ *
+ * @param cards - Optional initial cards
+ * @param owner - Optional owner player ID
+ * @returns Graveyard zone
+ *
+ * @example
+ * ```typescript
+ * const graveyard = createTestGraveyard(
+ *   ['dead-card1', 'dead-card2'],
+ *   'player1'
+ * );
+ * ```
+ */
+export function createTestGraveyard(
+  cards: CardId[] = [],
+  owner?: PlayerId,
+): Zone {
+  const id = createZoneId(`test-graveyard-${zoneCounter++}`);
+
+  return {
+    config: {
+      id,
+      name: owner ? `${owner} Graveyard` : "Test Graveyard",
+      visibility: "public",
+      ordered: true,
+      faceDown: false,
+      owner,
+    },
+    cards: [...cards],
+  };
+}
+
+/**
+ * Reset the zone counter (useful for deterministic test IDs)
+ *
+ * @example
+ * ```typescript
+ * resetZoneCounter();
+ * const zone1 = createTestZone(); // test-zone-0
+ * const zone2 = createTestZone(); // test-zone-1
+ * ```
+ */
+export function resetZoneCounter(): void {
+  zoneCounter = 0;
+}

package/src/types/branded-utils.ts

@@ -0,0 +1,54 @@
+import { nanoid } from "nanoid";
+import type { CardId, GameId, PlayerId, ZoneId } from "./branded";
+
+/**
+ * Creates a CardId from a string or generates a new unique ID
+ * @param id - Optional ID string. If not provided, generates a new unique ID
+ * @returns A branded CardId
+ */
+export function createCardId(): CardId;
+export function createCardId(id: string): CardId;
+export function createCardId(id?: string): CardId {
+  // Type assertion is acceptable here as this is the only way to create branded types
+  // biome-ignore lint/suspicious/noExplicitAny: Required for branded type creation
+  return (id ?? nanoid()) as any;
+}
+
+/**
+ * Creates a PlayerId from a string or generates a new unique ID
+ * @param id - Optional ID string. If not provided, generates a new unique ID
+ * @returns A branded PlayerId
+ */
+export function createPlayerId(): PlayerId;
+export function createPlayerId(id: string): PlayerId;
+export function createPlayerId(id?: string): PlayerId {
+  // Type assertion is acceptable here as this is the only way to create branded types
+  // biome-ignore lint/suspicious/noExplicitAny: Required for branded type creation
+  return (id ?? nanoid()) as any;
+}
+
+/**
+ * Creates a GameId from a string or generates a new unique ID
+ * @param id - Optional ID string. If not provided, generates a new unique ID
+ * @returns A branded GameId
+ */
+export function createGameId(): GameId;
+export function createGameId(id: string): GameId;
+export function createGameId(id?: string): GameId {
+  // Type assertion is acceptable here as this is the only way to create branded types
+  // biome-ignore lint/suspicious/noExplicitAny: Required for branded type creation
+  return (id ?? nanoid()) as any;
+}
+
+/**
+ * Creates a ZoneId from a string or generates a new unique ID
+ * @param id - Optional ID string. If not provided, generates a new unique ID
+ * @returns A branded ZoneId
+ */
+export function createZoneId(): ZoneId;
+export function createZoneId(id: string): ZoneId;
+export function createZoneId(id?: string): ZoneId {
+  // Type assertion is acceptable here as this is the only way to create branded types
+  // biome-ignore lint/suspicious/noExplicitAny: Required for branded type creation
+  return (id ?? nanoid()) as any;
+}