@drmxrcy/tcg-core 0.0.0-202602060542

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

@@ -0,0 +1,236 @@
+import { describe, expect, it } from "bun:test";
+import type { CardId, PlayerId } from "../types";
+import type { CardOperations } from "./card-operations";
+
+describe("CardOperations Interface", () => {
+  // Mock card metadata type for testing
+  type TestCardMeta = {
+    damage?: number;
+    exerted?: boolean;
+    counters?: number;
+    effects?: string[];
+  };
+
+  // Mock implementation for testing the interface structure
+  const createMockCardOperations = (): CardOperations<TestCardMeta> => {
+    const cardMetas: Record<string, TestCardMeta> = {
+      "card-1": { damage: 0, exerted: false },
+      "card-2": { damage: 3, exerted: true, counters: 5 },
+    };
+
+    const cardOwners: Record<string, string> = {
+      "card-1": "player-1",
+      "card-2": "player-2",
+    };
+
+    return {
+      getCardMeta: (cardId) => {
+        return cardMetas[cardId] || {};
+      },
+
+      updateCardMeta: (cardId, meta) => {
+        if (!cardMetas[cardId]) {
+          cardMetas[cardId] = {};
+        }
+        Object.assign(cardMetas[cardId], meta);
+      },
+
+      setCardMeta: (cardId, meta) => {
+        cardMetas[cardId] = meta;
+      },
+
+      getCardOwner: (cardId) => {
+        return cardOwners[cardId] as unknown as PlayerId | undefined;
+      },
+
+      queryCards: (predicate) => {
+        const results: CardId[] = [];
+        for (const cardId in cardMetas) {
+          if (predicate(cardId as CardId, cardMetas[cardId])) {
+            results.push(cardId as CardId);
+          }
+        }
+        return results;
+      },
+    };
+  };
+
+  describe("getCardMeta", () => {
+    it("should return card metadata", () => {
+      const ops = createMockCardOperations();
+
+      const meta = ops.getCardMeta("card-1" as CardId);
+
+      expect(meta.damage).toBe(0);
+      expect(meta.exerted).toBe(false);
+    });
+
+    it("should return empty object for card without metadata", () => {
+      const ops = createMockCardOperations();
+
+      const meta = ops.getCardMeta("nonexistent-card" as CardId);
+
+      expect(meta).toEqual({});
+    });
+
+    it("should return partial metadata", () => {
+      const ops = createMockCardOperations();
+
+      const meta = ops.getCardMeta("card-2" as CardId);
+
+      expect(meta.damage).toBe(3);
+      expect(meta.exerted).toBe(true);
+      expect(meta.counters).toBe(5);
+    });
+  });
+
+  describe("updateCardMeta", () => {
+    it("should merge new metadata with existing", () => {
+      const ops = createMockCardOperations();
+
+      ops.updateCardMeta("card-1" as CardId, { damage: 2 });
+      const meta = ops.getCardMeta("card-1" as CardId);
+
+      expect(meta.damage).toBe(2);
+      expect(meta.exerted).toBe(false); // Preserved
+    });
+
+    it("should add new properties to existing metadata", () => {
+      const ops = createMockCardOperations();
+
+      ops.updateCardMeta("card-1" as CardId, { counters: 3 });
+      const meta = ops.getCardMeta("card-1" as CardId);
+
+      expect(meta.counters).toBe(3);
+      expect(meta.damage).toBe(0); // Preserved
+      expect(meta.exerted).toBe(false); // Preserved
+    });
+
+    it("should create metadata for card without existing metadata", () => {
+      const ops = createMockCardOperations();
+
+      ops.updateCardMeta("card-3" as CardId, { damage: 5 });
+      const meta = ops.getCardMeta("card-3" as CardId);
+
+      expect(meta.damage).toBe(5);
+    });
+  });
+
+  describe("setCardMeta", () => {
+    it("should replace existing metadata completely", () => {
+      const ops = createMockCardOperations();
+
+      ops.setCardMeta("card-2" as CardId, { damage: 10 });
+      const meta = ops.getCardMeta("card-2" as CardId);
+
+      expect(meta.damage).toBe(10);
+      expect(meta.exerted).toBeUndefined(); // Removed
+      expect(meta.counters).toBeUndefined(); // Removed
+    });
+
+    it("should set metadata for new card", () => {
+      const ops = createMockCardOperations();
+
+      ops.setCardMeta("card-3" as CardId, { damage: 7, exerted: true });
+      const meta = ops.getCardMeta("card-3" as CardId);
+
+      expect(meta.damage).toBe(7);
+      expect(meta.exerted).toBe(true);
+    });
+  });
+
+  describe("getCardOwner", () => {
+    it("should return the owner of a card", () => {
+      const ops = createMockCardOperations();
+
+      const owner = ops.getCardOwner("card-1" as CardId);
+
+      expect(owner).toBe("player-1" as unknown as PlayerId);
+    });
+
+    it("should return undefined for card without owner", () => {
+      const ops = createMockCardOperations();
+
+      const owner = ops.getCardOwner("nonexistent-card" as CardId);
+
+      expect(owner).toBeUndefined();
+    });
+  });
+
+  describe("queryCards", () => {
+    it("should find cards matching a predicate", () => {
+      const ops = createMockCardOperations();
+
+      const exertedCards = ops.queryCards(
+        (cardId, meta) => meta.exerted === true,
+      );
+
+      expect(exertedCards).toHaveLength(1);
+      expect(exertedCards).toContain("card-2");
+    });
+
+    it("should find cards with specific damage", () => {
+      const ops = createMockCardOperations();
+
+      const damagedCards = ops.queryCards(
+        (cardId, meta) => (meta.damage ?? 0) > 0,
+      );
+
+      expect(damagedCards).toHaveLength(1);
+      expect(damagedCards).toContain("card-2");
+    });
+
+    it("should return empty array when no cards match", () => {
+      const ops = createMockCardOperations();
+
+      const results = ops.queryCards((cardId, meta) => meta.counters === 999);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it("should support complex predicates", () => {
+      const ops = createMockCardOperations();
+
+      const results = ops.queryCards(
+        (cardId, meta) =>
+          (meta.damage ?? 0) > 0 &&
+          meta.exerted === true &&
+          (meta.counters ?? 0) >= 5,
+      );
+
+      expect(results).toHaveLength(1);
+      expect(results).toContain("card-2");
+    });
+  });
+
+  describe("Type Safety", () => {
+    it("should enforce CardId type for card identifiers", () => {
+      const ops = createMockCardOperations();
+
+      // This is a compile-time test
+      const meta = ops.getCardMeta("card-1" as unknown as CardId);
+
+      expect(meta).toBeDefined();
+    });
+
+    it("should enforce PlayerId type for owner", () => {
+      const ops = createMockCardOperations();
+
+      // This is a compile-time test
+      const owner = ops.getCardOwner("card-1" as unknown as CardId);
+
+      expect(owner !== undefined ? typeof owner : "undefined").toBe("string");
+    });
+
+    it("should enforce generic metadata type", () => {
+      const ops = createMockCardOperations();
+
+      // This is a compile-time test - metadata should have TestCardMeta shape
+      const meta = ops.getCardMeta("card-1" as unknown as CardId);
+
+      // These properties should exist on TestCardMeta
+      expect(typeof meta.damage).toBe("number");
+      expect(typeof meta.exerted).toBe("boolean");
+    });
+  });
+});

package/src/operations/card-operations.ts

@@ -0,0 +1,116 @@
+import type { CardId, PlayerId } from "../types";
+
+/**
+ * Card Operations Interface
+ *
+ * Provides API for managing card metadata without directly mutating internal state.
+ * These operations are the only way for moves to interact with card properties.
+ *
+ * Card metadata includes:
+ * - Dynamic properties (damage, counters, effects)
+ * - Gained/lost abilities
+ * - Temporary modifications
+ * - Status effects
+ *
+ * @template TCardMeta - Game-specific card metadata type
+ */
+export interface CardOperations<TCardMeta = any> {
+  /**
+   * Get card metadata (dynamic properties)
+   *
+   * @param cardId - ID of the card
+   * @returns Card metadata object (may be partial or empty)
+   *
+   * @example
+   * ```typescript
+   * const meta = cards.getCardMeta('card-1');
+   * if (meta.damage && meta.damage > 0) {
+   *   // Card is damaged
+   * }
+   * ```
+   */
+  getCardMeta(cardId: CardId): Partial<TCardMeta>;
+
+  /**
+   * Update card metadata (merge with existing)
+   *
+   * Merges the provided metadata with existing metadata.
+   * Use this to modify specific properties without affecting others.
+   *
+   * @param cardId - ID of the card
+   * @param meta - Partial metadata to merge
+   *
+   * @example
+   * ```typescript
+   * // Add 2 damage without affecting other properties
+   * const current = cards.getCardMeta('card-1');
+   * cards.updateCardMeta('card-1', {
+   *   damage: (current.damage || 0) + 2
+   * });
+   * ```
+   */
+  updateCardMeta(cardId: CardId, meta: Partial<TCardMeta>): void;
+
+  /**
+   * Set card metadata (replace completely)
+   *
+   * Replaces all existing metadata with the provided metadata.
+   * Use this for complete state replacement.
+   *
+   * @param cardId - ID of the card
+   * @param meta - Complete metadata to set
+   *
+   * @example
+   * ```typescript
+   * // Reset card to pristine state
+   * cards.setCardMeta('card-1', {
+   *   damage: 0,
+   *   exerted: false,
+   *   effects: []
+   * });
+   * ```
+   */
+  setCardMeta(cardId: CardId, meta: TCardMeta): void;
+
+  /**
+   * Get card owner
+   *
+   * @param cardId - ID of the card
+   * @returns Player ID of the owner, or undefined if card doesn't exist
+   *
+   * @example
+   * ```typescript
+   * const owner = cards.getCardOwner('card-1');
+   * if (owner === context.playerId) {
+   *   // Player owns this card
+   * }
+   * ```
+   */
+  getCardOwner(cardId: CardId): PlayerId | undefined;
+
+  /**
+   * Query cards by metadata criteria
+   *
+   * Finds all cards matching a predicate function.
+   * Useful for complex queries involving multiple metadata properties.
+   *
+   * @param predicate - Function that returns true for matching cards
+   * @returns Array of card IDs that match the predicate
+   *
+   * @example
+   * ```typescript
+   * // Find all exerted cards with damage
+   * const damagedExerted = cards.queryCards((cardId, meta) =>
+   *   meta.exerted === true && (meta.damage || 0) > 0
+   * );
+   *
+   * // Find all cards with a specific effect
+   * const poisoned = cards.queryCards((cardId, meta) =>
+   *   meta.effects?.includes('poisoned')
+   * );
+   * ```
+   */
+  queryCards(
+    predicate: (cardId: CardId, meta: Partial<TCardMeta>) => boolean,
+  ): CardId[];
+}

package/src/operations/card-registry-impl.test.ts

@@ -0,0 +1,251 @@
+import { describe, expect, it } from "bun:test";
+import { createCardRegistry } from "./card-registry-impl";
+
+describe("CardRegistry Implementation", () => {
+  type TestCardDef = {
+    id: string;
+    name: string;
+    cost: number;
+    type: "monster" | "spell" | "trap";
+    attack?: number;
+    defense?: number;
+  };
+
+  const testCards: Record<string, TestCardDef> = {
+    "monster-1": {
+      id: "monster-1",
+      name: "Blue Eyes",
+      cost: 8,
+      type: "monster",
+      attack: 3000,
+      defense: 2500,
+    },
+    "monster-2": {
+      id: "monster-2",
+      name: "Dark Magician",
+      cost: 7,
+      type: "monster",
+      attack: 2500,
+      defense: 2100,
+    },
+    "spell-1": {
+      id: "spell-1",
+      name: "Lightning Bolt",
+      cost: 1,
+      type: "spell",
+    },
+    "trap-1": {
+      id: "trap-1",
+      name: "Mirror Force",
+      cost: 3,
+      type: "trap",
+    },
+  };
+
+  describe("createCardRegistry", () => {
+    it("should create registry from card definitions", () => {
+      const registry = createCardRegistry(testCards);
+
+      expect(registry.getCardCount()).toBe(4);
+      expect(registry.hasCard("monster-1")).toBe(true);
+      expect(registry.hasCard("spell-1")).toBe(true);
+    });
+
+    it("should create empty registry with no cards", () => {
+      const registry = createCardRegistry<TestCardDef>();
+
+      expect(registry.getCardCount()).toBe(0);
+      expect(registry.getAllCards()).toHaveLength(0);
+    });
+
+    it("should create empty registry with empty object", () => {
+      const registry = createCardRegistry<TestCardDef>({});
+
+      expect(registry.getCardCount()).toBe(0);
+      expect(registry.getAllCards()).toHaveLength(0);
+    });
+  });
+
+  describe("getCard", () => {
+    it("should return card definition by ID", () => {
+      const registry = createCardRegistry(testCards);
+
+      const card = registry.getCard("monster-1");
+
+      expect(card).toBeDefined();
+      expect(card?.name).toBe("Blue Eyes");
+      expect(card?.cost).toBe(8);
+      expect(card?.attack).toBe(3000);
+    });
+
+    it("should return undefined for nonexistent card", () => {
+      const registry = createCardRegistry(testCards);
+
+      const card = registry.getCard("nonexistent");
+
+      expect(card).toBeUndefined();
+    });
+
+    it("should handle different card types", () => {
+      const registry = createCardRegistry(testCards);
+
+      const monster = registry.getCard("monster-1");
+      const spell = registry.getCard("spell-1");
+
+      expect(monster?.type).toBe("monster");
+      expect(spell?.type).toBe("spell");
+    });
+  });
+
+  describe("hasCard", () => {
+    it("should return true for existing card", () => {
+      const registry = createCardRegistry(testCards);
+
+      expect(registry.hasCard("monster-1")).toBe(true);
+      expect(registry.hasCard("spell-1")).toBe(true);
+      expect(registry.hasCard("trap-1")).toBe(true);
+    });
+
+    it("should return false for nonexistent card", () => {
+      const registry = createCardRegistry(testCards);
+
+      expect(registry.hasCard("nonexistent")).toBe(false);
+      expect(registry.hasCard("unknown-card")).toBe(false);
+    });
+  });
+
+  describe("getAllCards", () => {
+    it("should return all card definitions", () => {
+      const registry = createCardRegistry(testCards);
+
+      const allCards = registry.getAllCards();
+
+      expect(allCards).toHaveLength(4);
+      expect(allCards.map((c) => c.id)).toContain("monster-1");
+      expect(allCards.map((c) => c.id)).toContain("monster-2");
+      expect(allCards.map((c) => c.id)).toContain("spell-1");
+      expect(allCards.map((c) => c.id)).toContain("trap-1");
+    });
+
+    it("should return empty array for empty registry", () => {
+      const registry = createCardRegistry<TestCardDef>();
+
+      const allCards = registry.getAllCards();
+
+      expect(allCards).toHaveLength(0);
+    });
+
+    it("should return new array instance each time", () => {
+      const registry = createCardRegistry(testCards);
+
+      const arr1 = registry.getAllCards();
+      const arr2 = registry.getAllCards();
+
+      expect(arr1).not.toBe(arr2); // Different instances
+      expect(arr1).toEqual(arr2); // Same content
+    });
+  });
+
+  describe("queryCards", () => {
+    it("should find cards by type", () => {
+      const registry = createCardRegistry(testCards);
+
+      const monsters = registry.queryCards((card) => card.type === "monster");
+
+      expect(monsters).toHaveLength(2);
+      expect(monsters.every((c) => c.type === "monster")).toBe(true);
+      expect(monsters.map((c) => c.id)).toContain("monster-1");
+      expect(monsters.map((c) => c.id)).toContain("monster-2");
+    });
+
+    it("should find cards by cost", () => {
+      const registry = createCardRegistry(testCards);
+
+      const expensive = registry.queryCards((card) => card.cost >= 7);
+
+      expect(expensive).toHaveLength(2);
+      expect(expensive.map((c) => c.id)).toContain("monster-1");
+      expect(expensive.map((c) => c.id)).toContain("monster-2");
+    });
+
+    it("should support complex predicates", () => {
+      const registry = createCardRegistry(testCards);
+
+      const strongMonsters = registry.queryCards(
+        (card) => card.type === "monster" && (card.attack ?? 0) >= 2500,
+      );
+
+      expect(strongMonsters).toHaveLength(2);
+      expect(strongMonsters.every((c) => c.type === "monster")).toBe(true);
+      expect(strongMonsters.every((c) => (c.attack ?? 0) >= 2500)).toBe(true);
+    });
+
+    it("should return empty array when no matches", () => {
+      const registry = createCardRegistry(testCards);
+
+      const results = registry.queryCards((card) => card.cost > 100);
+
+      expect(results).toHaveLength(0);
+    });
+
+    it("should handle predicates on optional properties", () => {
+      const registry = createCardRegistry(testCards);
+
+      const withAttack = registry.queryCards(
+        (card) => card.attack !== undefined,
+      );
+
+      expect(withAttack).toHaveLength(2);
+      expect(withAttack.every((c) => c.type === "monster")).toBe(true);
+    });
+  });
+
+  describe("getCardCount", () => {
+    it("should return total number of cards", () => {
+      const registry = createCardRegistry(testCards);
+
+      expect(registry.getCardCount()).toBe(4);
+    });
+
+    it("should return 0 for empty registry", () => {
+      const registry = createCardRegistry<TestCardDef>();
+
+      expect(registry.getCardCount()).toBe(0);
+    });
+  });
+
+  describe("Immutability", () => {
+    it("should not expose internal card definitions directly", () => {
+      const registry = createCardRegistry(testCards);
+
+      const card1 = registry.getCard("monster-1");
+      const card2 = registry.getCard("monster-1");
+
+      // Should return the same object (not a copy)
+      // This is fine since card definitions are static/immutable
+      expect(card1).toBeDefined();
+      expect(card2).toBeDefined();
+      if (card1 && card2) {
+        expect(card1).toBe(card2);
+      }
+    });
+
+    it("should return new arrays for getAllCards", () => {
+      const registry = createCardRegistry(testCards);
+
+      const all1 = registry.getAllCards();
+      const all2 = registry.getAllCards();
+
+      expect(all1).not.toBe(all2);
+    });
+
+    it("should return new arrays for queryCards", () => {
+      const registry = createCardRegistry(testCards);
+
+      const query1 = registry.queryCards((c) => c.type === "monster");
+      const query2 = registry.queryCards((c) => c.type === "monster");
+
+      expect(query1).not.toBe(query2);
+    });
+  });
+});

package/src/operations/card-registry-impl.ts

@@ -0,0 +1,70 @@
+import type { CardRegistry } from "./card-registry";
+
+/**
+ * Creates a CardRegistry implementation from a record or array of card definitions
+ *
+ * @param cards - Record mapping card definition IDs to card definitions,
+ *                OR array of definitions with `id` property
+ * @returns CardRegistry implementation
+ *
+ * @example
+ * ```typescript
+ * // From record:
+ * const cards = {
+ *   'pikachu': { id: 'pikachu', name: 'Pikachu', cost: 3 },
+ *   'charizard': { id: 'charizard', name: 'Charizard', cost: 8 },
+ * };
+ * const registry = createCardRegistry(cards);
+ *
+ * // From array:
+ * const cardArray = [
+ *   { id: 'pikachu', name: 'Pikachu', cost: 3 },
+ *   { id: 'charizard', name: 'Charizard', cost: 8 },
+ * ];
+ * const registry = createCardRegistry(cardArray);
+ *
+ * const pikachu = registry.getCard('pikachu');
+ * ```
+ */
+export function createCardRegistry<TCardDefinition>(
+  cards:
+    | Record<string, TCardDefinition>
+    | (TCardDefinition & { id: string })[] = {} as Record<
+    string,
+    TCardDefinition
+  >,
+): CardRegistry<TCardDefinition> {
+  // Convert array to record if needed
+  const cardsRecord: Record<string, TCardDefinition> = Array.isArray(cards)
+    ? cards.reduce(
+        (acc, card) => {
+          acc[card.id] = card;
+          return acc;
+        },
+        {} as Record<string, TCardDefinition>,
+      )
+    : cards;
+  return {
+    getCard(definitionId: string): TCardDefinition | undefined {
+      return cardsRecord[definitionId];
+    },
+
+    hasCard(definitionId: string): boolean {
+      return definitionId in cardsRecord;
+    },
+
+    getAllCards(): TCardDefinition[] {
+      return Object.values(cardsRecord);
+    },
+
+    queryCards(
+      predicate: (card: TCardDefinition) => boolean,
+    ): TCardDefinition[] {
+      return Object.values(cardsRecord).filter(predicate);
+    },
+
+    getCardCount(): number {
+      return Object.keys(cardsRecord).length;
+    },
+  };
+}