@drmxrcy/tcg-core 0.0.0-202602060542

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

@@ -0,0 +1,128 @@
+import type { CardId, PlayerId } from "../types";
+import type { Zone } from "./zone";
+import { moveCard } from "./zone-operations";
+
+/**
+ * Creates a record of zones for each player with optional initialization
+ * @param players - Array of player IDs
+ * @param initialValue - Optional factory function to create initial value for each player
+ * @returns Record mapping each player to their value
+ *
+ * @example
+ * ```typescript
+ * // Create empty arrays for each player
+ * const hands = createPlayerZones(players);
+ *
+ * // Create with custom initial values
+ * const decks = createPlayerZones(players, () => []);
+ *
+ * // Create with complex initial values
+ * const zones = createPlayerZones(players, () => ({
+ *   hand: [],
+ *   deck: [],
+ *   graveyard: []
+ * }));
+ * ```
+ */
+export function createPlayerZones<T>(
+  players: PlayerId[],
+  initialValue?: () => T,
+): Record<PlayerId, T> {
+  const zones = {} as Record<PlayerId, T>;
+
+  for (const playerId of players) {
+    zones[playerId] = initialValue ? initialValue() : (undefined as T);
+  }
+
+  return zones;
+}
+
+/**
+ * Moves a card between zones in a flat zone state object
+ * @param state - Object containing zones as properties
+ * @param fromZoneKey - Key of the source zone in state
+ * @param toZoneKey - Key of the destination zone in state
+ * @param cardId - Card to move
+ * @param position - Optional position in destination zone
+ * @returns New state object with updated zones
+ *
+ * @example
+ * ```typescript
+ * const state = {
+ *   hand: createZone(...),
+ *   deck: createZone(...),
+ * };
+ *
+ * // Move card from hand to deck
+ * const newState = moveCardInState(state, "hand", "deck", cardId);
+ *
+ * // Move to specific position
+ * const newState2 = moveCardInState(state, "hand", "deck", cardId, 0);
+ * ```
+ */
+export function moveCardInState<
+  TState extends Record<string, Zone>,
+  TFromKey extends keyof TState,
+  TToKey extends keyof TState,
+>(
+  state: TState,
+  fromZoneKey: TFromKey,
+  toZoneKey: TToKey,
+  cardId: CardId,
+  position?: number,
+): TState {
+  const fromZone = state[fromZoneKey];
+  const toZone = state[toZoneKey];
+
+  if (!(fromZone && toZone)) {
+    throw new Error(
+      `Zone not found: ${fromZone ? String(toZoneKey) : String(fromZoneKey)}`,
+    );
+  }
+
+  const { fromZone: updatedFrom, toZone: updatedTo } = moveCard(
+    fromZone,
+    toZone,
+    cardId,
+    position,
+  );
+
+  return {
+    ...state,
+    [fromZoneKey]: updatedFrom,
+    [toZoneKey]: updatedTo,
+  };
+}
+
+/**
+ * Finds which zone contains a card in a flat zone state object
+ * @param state - Object containing zones as properties
+ * @param cardId - Card to find
+ * @returns Key of the zone containing the card, or undefined if not found
+ *
+ * @example
+ * ```typescript
+ * const state = {
+ *   hand: createZone(..., [card1, card2]),
+ *   deck: createZone(..., [card3]),
+ * };
+ *
+ * const zoneName = getCardZone(state, card1);
+ * // Returns: "hand"
+ *
+ * const missing = getCardZone(state, card4);
+ * // Returns: undefined
+ * ```
+ */
+export function getCardZone<TState extends Record<string, Zone>>(
+  state: TState,
+  cardId: CardId,
+): keyof TState | undefined {
+  for (const key in state) {
+    const zone = state[key];
+    if (zone && zone.cards.includes(cardId)) {
+      return key;
+    }
+  }
+  return undefined;
+}

package/src/zones/zone-visibility.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it } from "bun:test";
+import { createCardId, createPlayerId, createZoneId } from "../types";
+import { createZone } from "./zone-factory";
+import { filterZoneByVisibility } from "./zone-visibility";
+
+describe("Zone Visibility", () => {
+  describe("filterZoneByVisibility", () => {
+    it("should show all cards in public zone to all players", () => {
+      const cards = [createCardId("card-1"), createCardId("card-2")];
+      const zone = createZone(
+        {
+          id: createZoneId("play"),
+          name: "Play Area",
+          visibility: "public",
+          ordered: false,
+        },
+        cards,
+      );
+
+      const viewerId = createPlayerId("player-1");
+      const filtered = filterZoneByVisibility(zone, viewerId);
+
+      expect(filtered.cards).toEqual(cards);
+      expect(filtered.cards).toHaveLength(2);
+    });
+
+    it("should show cards in private zone to owner", () => {
+      const ownerId = createPlayerId("player-1");
+      const cards = [createCardId("card-1"), createCardId("card-2")];
+      const zone = createZone(
+        {
+          id: createZoneId("hand"),
+          name: "Hand",
+          visibility: "private",
+          ordered: false,
+          owner: ownerId,
+        },
+        cards,
+      );
+
+      const filtered = filterZoneByVisibility(zone, ownerId);
+
+      expect(filtered.cards).toEqual(cards);
+    });
+
+    it("should hide cards in private zone from non-owner", () => {
+      const ownerId = createPlayerId("player-1");
+      const viewerId = createPlayerId("player-2");
+      const cards = [createCardId("card-1"), createCardId("card-2")];
+      const zone = createZone(
+        {
+          id: createZoneId("hand"),
+          name: "Hand",
+          visibility: "private",
+          ordered: false,
+          owner: ownerId,
+        },
+        cards,
+      );
+
+      const filtered = filterZoneByVisibility(zone, viewerId);
+
+      expect(filtered.cards).toHaveLength(0);
+      expect(filtered.config).toEqual(zone.config);
+    });
+
+    it("should hide all cards in secret zone from all players", () => {
+      const cards = [createCardId("card-1"), createCardId("card-2")];
+      const zone = createZone(
+        {
+          id: createZoneId("deck"),
+          name: "Deck",
+          visibility: "secret",
+          ordered: true,
+          faceDown: true,
+        },
+        cards,
+      );
+
+      const viewerId = createPlayerId("player-1");
+      const filtered = filterZoneByVisibility(zone, viewerId);
+
+      expect(filtered.cards).toHaveLength(0);
+    });
+
+    it("should show card count but hide contents for private zone", () => {
+      const ownerId = createPlayerId("player-1");
+      const viewerId = createPlayerId("player-2");
+      const cards = [
+        createCardId("card-1"),
+        createCardId("card-2"),
+        createCardId("card-3"),
+      ];
+      const zone = createZone(
+        {
+          id: createZoneId("hand"),
+          name: "Hand",
+          visibility: "private",
+          ordered: false,
+          owner: ownerId,
+        },
+        cards,
+      );
+
+      const filtered = filterZoneByVisibility(zone, viewerId);
+
+      // Config should be preserved so count can be determined
+      expect(filtered.config).toEqual(zone.config);
+      // But cards should be empty
+      expect(filtered.cards).toHaveLength(0);
+    });
+
+    it("should show card count but hide contents for secret zone", () => {
+      const cards = [
+        createCardId("card-1"),
+        createCardId("card-2"),
+        createCardId("card-3"),
+      ];
+      const zone = createZone(
+        {
+          id: createZoneId("deck"),
+          name: "Deck",
+          visibility: "secret",
+          ordered: true,
+        },
+        cards,
+      );
+
+      const viewerId = createPlayerId("player-1");
+      const filtered = filterZoneByVisibility(zone, viewerId);
+
+      // Config preserved
+      expect(filtered.config).toEqual(zone.config);
+      // Cards hidden
+      expect(filtered.cards).toHaveLength(0);
+    });
+
+    it("should handle zone without owner as public", () => {
+      const cards = [createCardId("card-1"), createCardId("card-2")];
+      const zone = createZone(
+        {
+          id: createZoneId("graveyard"),
+          name: "Graveyard",
+          visibility: "public",
+          ordered: true,
+        },
+        cards,
+      );
+
+      const viewerId = createPlayerId("player-1");
+      const filtered = filterZoneByVisibility(zone, viewerId);
+
+      expect(filtered.cards).toEqual(cards);
+    });
+  });
+});

package/src/zones/zone-visibility.ts

@@ -0,0 +1,36 @@
+import { produce } from "immer";
+import type { PlayerId } from "../types";
+import type { Zone } from "./zone";
+
+/**
+ * Filters a zone based on visibility rules and the viewing player
+ * @param zone - Zone to filter
+ * @param viewerId - ID of the player viewing the zone
+ * @returns Filtered zone with appropriate cards visible
+ */
+export function filterZoneByVisibility(zone: Zone, viewerId: PlayerId): Zone {
+  // Public zones: everyone sees everything
+  if (zone.config.visibility === "public") {
+    return zone;
+  }
+
+  // Private zones: owner sees everything, others see nothing
+  if (zone.config.visibility === "private") {
+    if (zone.config.owner === viewerId) {
+      return zone;
+    }
+    // Non-owner sees config but no cards
+    return produce(zone, (draft) => {
+      draft.cards = [];
+    });
+  }
+
+  // Secret zones: no one sees card details
+  if (zone.config.visibility === "secret") {
+    return produce(zone, (draft) => {
+      draft.cards = [];
+    });
+  }
+
+  return zone;
+}

package/src/zones/zone.test.ts

@@ -0,0 +1,186 @@
+import { describe, expect, it } from "bun:test";
+import type { CardId, PlayerId, ZoneId } from "../types";
+import type { CardZoneConfig, Zone, ZoneVisibility } from "./zone";
+
+describe("Zone Type Definitions", () => {
+  describe("ZoneVisibility", () => {
+    it("should support public visibility type", () => {
+      const visibility: ZoneVisibility = "public";
+      expect(visibility).toBe("public");
+    });
+
+    it("should support private visibility type", () => {
+      const visibility: ZoneVisibility = "private";
+      expect(visibility).toBe("private");
+    });
+
+    it("should support secret visibility type", () => {
+      const visibility: ZoneVisibility = "secret";
+      expect(visibility).toBe("secret");
+    });
+  });
+
+  describe("ZoneConfig", () => {
+    it("should define valid zone configuration structure", () => {
+      const config: CardZoneConfig = {
+        id: "deck" as ZoneId,
+        name: "Deck",
+        visibility: "secret",
+        ordered: true,
+        faceDown: true,
+      };
+
+      expect(String(config.id)).toBe("deck");
+      expect(config.name).toBe("Deck");
+      expect(config.visibility).toBe("secret");
+      expect(config.ordered).toBe(true);
+      expect(config.faceDown).toBe(true);
+    });
+
+    it("should support optional owner property", () => {
+      const configWithOwner: CardZoneConfig = {
+        id: "hand" as ZoneId,
+        name: "Hand",
+        visibility: "private",
+        ordered: false,
+        owner: "player-1" as PlayerId,
+      };
+
+      expect(configWithOwner.owner).toBeDefined();
+      expect(typeof configWithOwner.owner).toBe("string");
+    });
+
+    it("should support optional maxSize property", () => {
+      const configWithMaxSize: CardZoneConfig = {
+        id: "hand" as ZoneId,
+        name: "Hand",
+        visibility: "private",
+        ordered: false,
+        maxSize: 7,
+      };
+
+      expect(configWithMaxSize.maxSize).toBe(7);
+    });
+
+    it("should work without optional properties", () => {
+      const minimalConfig: CardZoneConfig = {
+        id: "play" as ZoneId,
+        name: "Play Area",
+        visibility: "public",
+        ordered: false,
+      };
+
+      expect(minimalConfig.owner).toBeUndefined();
+      expect(minimalConfig.maxSize).toBeUndefined();
+      expect(minimalConfig.faceDown).toBeUndefined();
+    });
+  });
+
+  describe("Zone", () => {
+    it("should define valid zone structure with config and cards", () => {
+      const zone: Zone = {
+        config: {
+          id: "deck" as ZoneId,
+          name: "Deck",
+          visibility: "secret",
+          ordered: true,
+          faceDown: true,
+        },
+        cards: [],
+      };
+
+      expect(zone.config).toBeDefined();
+      expect(zone.cards).toBeInstanceOf(Array);
+      expect(zone.cards).toHaveLength(0);
+    });
+
+    it("should support zone with card IDs", () => {
+      const cardId1 = "card-1" as CardId;
+      const cardId2 = "card-2" as CardId;
+
+      const zone: Zone = {
+        config: {
+          id: "hand" as ZoneId,
+          name: "Hand",
+          visibility: "private",
+          ordered: false,
+        },
+        cards: [cardId1, cardId2],
+      };
+
+      expect(zone.cards).toHaveLength(2);
+      expect(zone.cards[0]).toBe(cardId1);
+      expect(zone.cards[1]).toBe(cardId2);
+    });
+
+    it("should maintain card order when ordered is true", () => {
+      const cardIds = [
+        "card-1" as CardId,
+        "card-2" as CardId,
+        "card-3" as CardId,
+      ];
+
+      const orderedZone: Zone = {
+        config: {
+          id: "deck" as ZoneId,
+          name: "Deck",
+          visibility: "secret",
+          ordered: true,
+        },
+        cards: cardIds,
+      };
+
+      expect(orderedZone.cards[0]).toBe(cardIds[0]);
+      expect(orderedZone.cards[1]).toBe(cardIds[1]);
+      expect(orderedZone.cards[2]).toBe(cardIds[2]);
+    });
+  });
+
+  describe("Zone Type Safety", () => {
+    it("should enforce ZoneId type for zone config id", () => {
+      const zoneId = "deck" as ZoneId;
+      const config: CardZoneConfig = {
+        id: zoneId,
+        name: "Deck",
+        visibility: "secret",
+        ordered: true,
+      };
+
+      const _typeCheck: ZoneId = config.id;
+      expect(config.id).toBe(zoneId);
+    });
+
+    it("should enforce CardId array type for zone cards", () => {
+      const cardIds: CardId[] = ["card-1" as CardId, "card-2" as CardId];
+
+      const zone: Zone = {
+        config: {
+          id: "hand" as ZoneId,
+          name: "Hand",
+          visibility: "private",
+          ordered: false,
+        },
+        cards: cardIds,
+      };
+
+      const _typeCheck: CardId[] = zone.cards;
+      expect(zone.cards).toEqual(cardIds);
+    });
+
+    it("should enforce PlayerId type for owner", () => {
+      const playerId = "player-1" as PlayerId;
+      const config: CardZoneConfig = {
+        id: "hand" as ZoneId,
+        name: "Hand",
+        visibility: "private",
+        ordered: false,
+        owner: playerId,
+      };
+
+      if (config.owner) {
+        const _typeCheck: PlayerId = config.owner;
+        expect(config.owner).toBe(playerId);
+      }
+    });
+  });
+});

package/src/zones/zone.ts

@@ -0,0 +1,66 @@
+import type { CardId, PlayerId, ZoneId } from "../types";
+
+/**
+ * Zone visibility types
+ *
+ * - public: All players can see all cards (e.g., play area, graveyard)
+ * - private: Owner can see cards, opponents see count (e.g., hand)
+ * - secret: No one can see cards, only count (e.g., deck, face-down cards)
+ */
+export type ZoneVisibility = "public" | "private" | "secret";
+
+/**
+ * Zone configuration defining the properties and rules of a zone
+ */
+export type CardZoneConfig = {
+  /**
+   * Unique identifier for the zone
+   */
+  id: ZoneId;
+
+  /**
+   * Human-readable name of the zone
+   */
+  name: string;
+
+  /**
+   * Visibility rules for the zone
+   */
+  visibility: ZoneVisibility;
+
+  /**
+   * Whether card order matters in this zone
+   * True for decks, false for play areas
+   */
+  ordered: boolean;
+
+  /**
+   * Optional owner of the zone (undefined for shared zones)
+   */
+  owner?: PlayerId;
+
+  /**
+   * Whether cards are face-down by default
+   */
+  faceDown?: boolean;
+
+  /**
+   * Maximum number of cards allowed in the zone
+   */
+  maxSize?: number;
+};
+
+/**
+ * A zone containing cards with configuration
+ */
+export type Zone = {
+  /**
+   * Zone configuration
+   */
+  config: CardZoneConfig;
+
+  /**
+   * Cards currently in the zone
+   */
+  cards: CardId[];
+};