@drmxrcy/tcg-core 0.0.0-202602060542

package/src/types/branded.test.ts

@@ -0,0 +1,175 @@
+import { describe, expect, it } from "bun:test";
+import type { CardId, GameId, PlayerId, ZoneId } from "./branded";
+import {
+  createCardId,
+  createGameId,
+  createPlayerId,
+  createZoneId,
+} from "./branded-utils";
+
+describe("Branded Types", () => {
+  describe("createCardId", () => {
+    it("should create a CardId from a string literal", () => {
+      const cardId = createCardId("card-123");
+      expect(typeof cardId).toBe("string");
+      // Runtime value should match the input
+      expect(String(cardId)).toBe("card-123");
+      // Type assertion to verify it's properly typed
+      const _typeCheck: CardId = cardId;
+    });
+
+    it("should generate unique IDs when called without arguments", () => {
+      const id1 = createCardId();
+      const id2 = createCardId();
+      expect(id1).not.toBe(id2);
+    });
+
+    it("should generate IDs with proper format", () => {
+      const cardId = createCardId();
+      expect(typeof cardId).toBe("string");
+      expect(cardId.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("createPlayerId", () => {
+    it("should create a PlayerId from a string literal", () => {
+      const playerId = createPlayerId("player-456");
+      expect(typeof playerId).toBe("string");
+      // Runtime value should match the input
+      expect(String(playerId)).toBe("player-456");
+      // Type assertion to verify it's properly typed
+      const _typeCheck: PlayerId = playerId;
+    });
+
+    it("should generate unique IDs when called without arguments", () => {
+      const id1 = createPlayerId();
+      const id2 = createPlayerId();
+      expect(id1).not.toBe(id2);
+    });
+
+    it("should generate IDs with proper format", () => {
+      const playerId = createPlayerId();
+      expect(typeof playerId).toBe("string");
+      expect(playerId.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("createGameId", () => {
+    it("should create a GameId from a string literal", () => {
+      const gameId = createGameId("game-789");
+      expect(typeof gameId).toBe("string");
+      // Runtime value should match the input
+      expect(String(gameId)).toBe("game-789");
+      // Type assertion to verify it's properly typed
+      const _typeCheck: GameId = gameId;
+    });
+
+    it("should generate unique IDs when called without arguments", () => {
+      const id1 = createGameId();
+      const id2 = createGameId();
+      expect(id1).not.toBe(id2);
+    });
+
+    it("should generate IDs with proper format", () => {
+      const gameId = createGameId();
+      expect(typeof gameId).toBe("string");
+      expect(gameId.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("createZoneId", () => {
+    it("should create a ZoneId from a string literal", () => {
+      const zoneId = createZoneId("zone-abc");
+      expect(typeof zoneId).toBe("string");
+      // Runtime value should match the input
+      expect(String(zoneId)).toBe("zone-abc");
+      // Type assertion to verify it's properly typed
+      const _typeCheck: ZoneId = zoneId;
+    });
+
+    it("should generate unique IDs when called without arguments", () => {
+      const id1 = createZoneId();
+      const id2 = createZoneId();
+      expect(id1).not.toBe(id2);
+    });
+
+    it("should generate IDs with proper format", () => {
+      const zoneId = createZoneId();
+      expect(typeof zoneId).toBe("string");
+      expect(zoneId.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe("Type Safety", () => {
+    it("should prevent mixing different ID types at compile time", () => {
+      const cardId = createCardId("id-1");
+      const playerId = createPlayerId("id-2");
+
+      // This test verifies type safety at compile time
+      // The following would fail TypeScript compilation:
+      // const wrongAssignment1: CardId = playerId;
+      // const wrongAssignment2: PlayerId = cardId;
+
+      // But we can verify runtime values are still just strings
+      expect(typeof cardId).toBe("string");
+      expect(typeof playerId).toBe("string");
+    });
+
+    it("should allow assignment of branded types to their brand type", () => {
+      const cardId: CardId = createCardId("card-123");
+      const acceptsCardId = (id: CardId): CardId => id;
+
+      expect(acceptsCardId(cardId)).toBe(cardId);
+    });
+
+    it("should work with arrays and collections", () => {
+      const cardIds: CardId[] = [
+        createCardId("1"),
+        createCardId("2"),
+        createCardId("3"),
+      ];
+
+      expect(cardIds).toHaveLength(3);
+      expect(cardIds.every((id) => typeof id === "string")).toBe(true);
+    });
+
+    it("should work with Set and Map", () => {
+      const cardIdSet = new Set<CardId>([createCardId("1"), createCardId("2")]);
+      const cardIdMap = new Map<CardId, string>([
+        [createCardId("1"), "Card One"],
+        [createCardId("2"), "Card Two"],
+      ]);
+
+      expect(cardIdSet.size).toBe(2);
+      expect(cardIdMap.size).toBe(2);
+    });
+  });
+
+  describe("ID Generation Consistency", () => {
+    it("should generate IDs of consistent length", () => {
+      const ids = [
+        createCardId(),
+        createPlayerId(),
+        createGameId(),
+        createZoneId(),
+      ];
+
+      const lengths = ids.map((id) => id.length);
+      expect(new Set(lengths).size).toBe(1); // All same length
+    });
+
+    it("should generate URL-safe IDs", () => {
+      const ids = [
+        createCardId(),
+        createPlayerId(),
+        createGameId(),
+        createZoneId(),
+      ];
+
+      for (const id of ids) {
+        // nanoid generates URL-safe characters: A-Za-z0-9_-
+        expect(id).toMatch(/^[A-Za-z0-9_-]+$/);
+      }
+    });
+  });
+});

package/src/types/branded.ts

@@ -0,0 +1,33 @@
+/**
+ * Branded Types
+ *
+ * Branded types provide compile-time type safety for primitive values
+ * to prevent mixing different ID types and other domain values.
+ */
+
+declare const brand: unique symbol;
+
+/**
+ * Base branded type that adds a compile-time brand to a value
+ */
+export type Brand<T, TBrand> = T & { readonly [brand]: TBrand };
+
+/**
+ * Card identifier - unique ID for a card instance in the game
+ */
+export type CardId = Brand<string, "CardId">;
+
+/**
+ * Player identifier - unique ID for a player in the game
+ */
+export type PlayerId = Brand<string, "PlayerId">;
+
+/**
+ * Game identifier - unique ID for a game session
+ */
+export type GameId = Brand<string, "GameId">;
+
+/**
+ * Zone identifier - unique ID for a zone in the game
+ */
+export type ZoneId = Brand<string, "ZoneId">;

package/src/types/index.ts

@@ -0,0 +1,8 @@
+export type { Brand, CardId, GameId, PlayerId, ZoneId } from "./branded";
+export {
+  createCardId,
+  createGameId,
+  createPlayerId,
+  createZoneId,
+} from "./branded-utils";
+export type { IState } from "./state";

package/src/types/state.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, it } from "bun:test";
+import type { CardZoneConfig } from "../zones";
+import type { CardId, PlayerId, ZoneId } from "./index";
+import type { InternalState, IState } from "./state";
+
+describe("InternalState", () => {
+  it("should allow defining zones with configuration and card lists", () => {
+    // Test that InternalState can hold zone data
+    type TestCardDef = { id: string; name: string };
+    type TestCardMeta = { damage?: number };
+
+    const zoneConfig: CardZoneConfig = {
+      id: "hand" as unknown as ZoneId,
+      name: "Hand",
+      visibility: "private",
+      ordered: false,
+    };
+
+    const internalState: InternalState<TestCardDef, TestCardMeta> = {
+      zones: {
+        hand: {
+          config: zoneConfig,
+          cardIds: ["card-1", "card-2"] as unknown as CardId[],
+        },
+      },
+      cards: {},
+      cardMetas: {},
+    };
+
+    expect(internalState.zones.hand.cardIds).toHaveLength(2);
+    expect(internalState.zones.hand.config.visibility).toBe("private");
+  });
+
+  it("should allow defining card instances with owner and zone", () => {
+    type TestCardDef = { id: string; name: string };
+    type TestCardMeta = { damage?: number };
+
+    const internalState: InternalState<TestCardDef, TestCardMeta> = {
+      zones: {},
+      cards: {
+        "card-1": {
+          definitionId: "pikachu",
+          owner: "player-1" as unknown as PlayerId,
+          controller: "player-1" as unknown as PlayerId,
+          zone: "hand" as unknown as ZoneId,
+        },
+      },
+      cardMetas: {},
+    };
+
+    expect(internalState.cards["card-1"].definitionId).toBe("pikachu");
+    expect(internalState.cards["card-1"].owner).toBe(
+      "player-1" as unknown as PlayerId,
+    );
+    expect(internalState.cards["card-1"].zone).toBe(
+      "hand" as unknown as ZoneId,
+    );
+  });
+
+  it("should allow defining card metadata for dynamic properties", () => {
+    type TestCardDef = { id: string };
+    type TestCardMeta = {
+      damage?: number;
+      exerted?: boolean;
+      effects?: string[];
+    };
+
+    const internalState: InternalState<TestCardDef, TestCardMeta> = {
+      zones: {},
+      cards: {},
+      cardMetas: {
+        "card-1": {
+          damage: 5,
+          exerted: true,
+          effects: ["poisoned"],
+        },
+      },
+    };
+
+    expect(internalState.cardMetas["card-1"].damage).toBe(5);
+    expect(internalState.cardMetas["card-1"].exerted).toBe(true);
+  });
+
+  it("should allow position tracking for ordered zones", () => {
+    type TestCardDef = { id: string };
+    type TestCardMeta = Record<string, never>;
+
+    const internalState: InternalState<TestCardDef, TestCardMeta> = {
+      zones: {},
+      cards: {
+        "card-1": {
+          definitionId: "card-def-1",
+          owner: "player-1" as unknown as PlayerId,
+          controller: "player-1" as unknown as PlayerId,
+          zone: "deck" as unknown as ZoneId,
+          position: 0, // Top of deck
+        },
+        "card-2": {
+          definitionId: "card-def-2",
+          owner: "player-1" as unknown as PlayerId,
+          controller: "player-1" as unknown as PlayerId,
+          zone: "deck" as unknown as ZoneId,
+          position: 1,
+        },
+      },
+      cardMetas: {},
+    };
+
+    expect(internalState.cards["card-1"].position).toBe(0);
+    expect(internalState.cards["card-2"].position).toBe(1);
+  });
+});
+
+describe("IState", () => {
+  it("should wrap external game state with internal framework state", () => {
+    type GameState = {
+      turnCount: number;
+      currentPlayer: string;
+    };
+
+    type TestCardDef = { id: string };
+    type TestCardMeta = { damage?: number };
+
+    const state: IState<GameState, TestCardDef, TestCardMeta> = {
+      internal: {
+        zones: {},
+        cards: {},
+        cardMetas: {},
+      },
+      external: {
+        turnCount: 1,
+        currentPlayer: "player-1",
+      },
+    };
+
+    // Games can access their state
+    expect(state.external.turnCount).toBe(1);
+    expect(state.external.currentPlayer).toBe("player-1");
+
+    // Framework manages internal state
+    expect(state.internal.zones).toEqual({});
+    expect(state.internal.cards).toEqual({});
+  });
+
+  it("should allow complex external state while framework manages infrastructure", () => {
+    type GameState = {
+      players: Array<{ id: string; score: number }>;
+      effects: Array<{ type: string; duration: number }>;
+    };
+
+    type TestCardDef = { id: string; name: string };
+    type TestCardMeta = { counters?: number };
+
+    const state: IState<GameState, TestCardDef, TestCardMeta> = {
+      internal: {
+        zones: {
+          hand: {
+            config: {
+              id: "hand" as unknown as ZoneId,
+              name: "Hand",
+              visibility: "private",
+              ordered: false,
+            },
+            cardIds: ["card-1"] as unknown as CardId[],
+          },
+        },
+        cards: {
+          "card-1": {
+            definitionId: "monster-1",
+            owner: "player-1" as unknown as PlayerId,
+            controller: "player-1" as unknown as PlayerId,
+            zone: "hand" as unknown as ZoneId,
+          },
+        },
+        cardMetas: {
+          "card-1": {
+            counters: 3,
+          },
+        },
+      },
+      external: {
+        players: [
+          { id: "player-1", score: 100 },
+          { id: "player-2", score: 85 },
+        ],
+        effects: [{ type: "global-buff", duration: 2 }],
+      },
+    };
+
+    // External game logic
+    expect(state.external.players).toHaveLength(2);
+    expect(state.external.effects[0].type).toBe("global-buff");
+
+    // Internal framework management
+    expect(state.internal.zones.hand.cardIds).toContain("card-1");
+    expect(state.internal.cardMetas["card-1"].counters).toBe(3);
+  });
+});

package/src/types/state.ts

@@ -0,0 +1,154 @@
+import type { CardZoneConfig } from "../zones";
+import type { CardId, PlayerId, ZoneId } from "./index";
+
+/**
+ * Internal State - Managed by the Framework
+ *
+ * This state contains infrastructure concerns that the framework handles:
+ * - Zone management (which card is in which zone)
+ * - Card instance tracking (instance ID, owner, location)
+ * - Card metadata (dynamic properties, counters, effects)
+ *
+ * Games cannot directly modify internal state. They must use the operations API
+ * provided in move context.
+ *
+ * @template TCardDefinition - Static card definition type (game-specific)
+ * @template TCardMeta - Dynamic card metadata type (game-specific)
+ */
+export type InternalState<TCardDefinition = any, TCardMeta = any> = {
+  /**
+   * Zone registry - Maps zone ID to zone data
+   *
+   * Each zone contains:
+   * - config: Zone configuration (visibility, ordering, etc.)
+   * - cardIds: Array of card instance IDs in this zone
+   *
+   * The framework maintains this mapping and ensures consistency.
+   */
+  zones: {
+    [zoneId: string]: {
+      config: CardZoneConfig;
+      cardIds: CardId[];
+    };
+  };
+
+  /**
+   * Card instance registry - Maps card instance ID to card data
+   *
+   * Each card instance contains:
+   * - definitionId: Reference to the static card definition
+   * - owner: Player who owns this card (never changes)
+   * - controller: Player currently controlling this card (can change via effects)
+   * - zone: Current zone containing this card
+   * - position: Optional position in zone (for ordered zones like decks)
+   *
+   * Card instances are created during game setup or through game actions.
+   * Note: Field names align with CardInstanceBase from cards/card-instance.ts
+   */
+  cards: {
+    [cardId: string]: {
+      /** Reference to card definition (static properties) */
+      definitionId: string;
+      /** Player who owns this card (never changes) */
+      owner: PlayerId;
+      /** Player currently controlling this card (can change via effects) */
+      controller: PlayerId;
+      /** Current zone containing this card */
+      zone: ZoneId;
+      /** Position in zone (for ordered zones) */
+      position?: number;
+    };
+  };
+
+  /**
+   * Card metadata registry - Maps card instance ID to dynamic metadata
+   *
+   * Stores mutable, game-specific card properties:
+   * - Damage/counters
+   * - Status effects (e.g., poisoned, stunned)
+   * - Gained abilities
+   * - Temporary modifications
+   *
+   * Metadata type is generic to allow game-specific structures.
+   */
+  cardMetas: {
+    [cardId: string]: TCardMeta;
+  };
+
+  /**
+   * On The Play (OTP) - Player who goes first
+   *
+   * Universal TCG concept. The OTP player typically goes first
+   * and may have different rules (e.g., no draw on first turn).
+   */
+  otp?: PlayerId;
+
+  /**
+   * Choosing First Player - Player designated to choose who goes first
+   *
+   * In TCGs like Lorcana, one player is randomly selected to choose
+   * who will be the starting player (OTP). This field tracks which
+   * player has that privilege.
+   *
+   * Typically set during game initialization and cleared after OTP is chosen.
+   */
+  choosingFirstPlayer?: PlayerId;
+
+  /**
+   * Players pending mulligan decision
+   *
+   * Tracks which players still need to decide whether to mulligan.
+   * Typically initialized with all players at game start.
+   */
+  pendingMulligan?: PlayerId[];
+};
+
+/**
+ * Complete Game State
+ *
+ * Separates framework-managed state (internal) from game-specific state (external).
+ *
+ * - internal: Zone/card management handled by framework
+ * - external: Game-specific state defined by game developers
+ *
+ * Moves receive operations API to modify internal state.
+ * Moves receive Immer draft of external state for direct modification.
+ *
+ * @template TState - Game-specific state type
+ * @template TCardDefinition - Static card definition type
+ * @template TCardMeta - Dynamic card metadata type
+ *
+ * @example
+ * ```typescript
+ * type MyGameState = { turnCount: number; currentPlayer: string };
+ * type MyCardDef = { id: string; name: string; cost: number };
+ * type MyCardMeta = { damage?: number; effects?: string[] };
+ *
+ * const state: IState<MyGameState, MyCardDef, MyCardMeta> = {
+ *   internal: {
+ *     zones: { ... },
+ *     cards: { ... },
+ *     cardMetas: { ... }
+ *   },
+ *   external: {
+ *     turnCount: 1,
+ *     currentPlayer: "player-1"
+ *   }
+ * };
+ * ```
+ */
+export type IState<TState, TCardDefinition = any, TCardMeta = any> = {
+  /**
+   * Framework-managed state
+   * Contains zone/card infrastructure
+   * Modified only through operations API
+   */
+  internal: InternalState<TCardDefinition, TCardMeta>;
+
+  /**
+   * Game-specific state
+   * Contains game logic state
+   * Modified directly via Immer draft in move reducers
+   */
+  external: TState;
+};