@drmxrcy/tcg-core 0.0.0-202602060542

package/src/validation/card-type-guards.test.ts

@@ -0,0 +1,242 @@
+import { describe, expect, it } from "bun:test";
+import type { CardDefinition } from "../cards/card-definition";
+import { isCardOfType } from "./card-type-guards";
+
+describe("isCardOfType", () => {
+  describe("basic usage", () => {
+    it("should create a type guard for card type", () => {
+      const isCreature = isCardOfType("creature");
+
+      const creature: CardDefinition = {
+        id: "dragon-1",
+        name: "Dragon",
+        type: "creature",
+        basePower: 5,
+        baseToughness: 5,
+      };
+
+      const instant: CardDefinition = {
+        id: "bolt-1",
+        name: "Lightning Bolt",
+        type: "instant",
+      };
+
+      expect(isCreature(creature)).toBe(true);
+      expect(isCreature(instant)).toBe(false);
+    });
+
+    it("should work with multiple card types", () => {
+      const isCreature = isCardOfType("creature");
+      const isInstant = isCardOfType("instant");
+      const isSorcery = isCardOfType("sorcery");
+
+      const creature: CardDefinition = {
+        id: "creature-1",
+        name: "Creature",
+        type: "creature",
+      };
+
+      const instant: CardDefinition = {
+        id: "instant-1",
+        name: "Instant",
+        type: "instant",
+      };
+
+      const sorcery: CardDefinition = {
+        id: "sorcery-1",
+        name: "Sorcery",
+        type: "sorcery",
+      };
+
+      expect(isCreature(creature)).toBe(true);
+      expect(isCreature(instant)).toBe(false);
+      expect(isCreature(sorcery)).toBe(false);
+
+      expect(isInstant(instant)).toBe(true);
+      expect(isInstant(creature)).toBe(false);
+      expect(isInstant(sorcery)).toBe(false);
+
+      expect(isSorcery(sorcery)).toBe(true);
+      expect(isSorcery(creature)).toBe(false);
+      expect(isSorcery(instant)).toBe(false);
+    });
+  });
+
+  describe("filtering arrays", () => {
+    it("should filter card arrays by type", () => {
+      const cards: CardDefinition[] = [
+        { id: "1", name: "Dragon", type: "creature" },
+        { id: "2", name: "Bolt", type: "instant" },
+        { id: "3", name: "Goblin", type: "creature" },
+        { id: "4", name: "Wrath", type: "sorcery" },
+        { id: "5", name: "Angel", type: "creature" },
+      ];
+
+      const isCreature = isCardOfType("creature");
+      const creatures = cards.filter(isCreature);
+
+      expect(creatures).toHaveLength(3);
+      expect(creatures.map((c) => c.name)).toEqual([
+        "Dragon",
+        "Goblin",
+        "Angel",
+      ]);
+    });
+
+    it("should work with Array.some and Array.every", () => {
+      const cards: CardDefinition[] = [
+        { id: "1", name: "Dragon", type: "creature" },
+        { id: "2", name: "Goblin", type: "creature" },
+      ];
+
+      const allCreatures: CardDefinition[] = [
+        { id: "3", name: "Angel", type: "creature" },
+      ];
+
+      const isCreature = isCardOfType("creature");
+
+      expect(cards.some(isCreature)).toBe(true);
+      expect(cards.every(isCreature)).toBe(true);
+      expect(allCreatures.every(isCreature)).toBe(true);
+    });
+  });
+
+  describe("type narrowing", () => {
+    it("should narrow types in conditional blocks", () => {
+      const card: CardDefinition = {
+        id: "dragon-1",
+        name: "Dragon",
+        type: "creature",
+        basePower: 5,
+        baseToughness: 5,
+      };
+
+      const isCreature = isCardOfType("creature");
+
+      if (isCreature(card)) {
+        // TypeScript should know card.type is "creature"
+        expect(card.type).toBe("creature");
+        expect(card.name).toBe("Dragon");
+      }
+    });
+  });
+
+  describe("game-specific types", () => {
+    it("should work with Gundam-specific card types", () => {
+      type GundamCard = CardDefinition & {
+        type: "unit" | "command" | "character" | "base";
+      };
+
+      const isUnit = isCardOfType<GundamCard>("unit");
+      const isCommand = isCardOfType<GundamCard>("command");
+
+      const unit: GundamCard = {
+        id: "gundam-1",
+        name: "RX-78-2 Gundam",
+        type: "unit",
+        basePower: 3,
+      };
+
+      const command: GundamCard = {
+        id: "command-1",
+        name: "All-Out Attack",
+        type: "command",
+      };
+
+      expect(isUnit(unit)).toBe(true);
+      expect(isUnit(command)).toBe(false);
+      expect(isCommand(command)).toBe(true);
+      expect(isCommand(unit)).toBe(false);
+    });
+
+    it("should work with Lorcana-specific card types", () => {
+      type LorcanaCard = CardDefinition & {
+        type: "character" | "action" | "item" | "location";
+      };
+
+      const isCharacter = isCardOfType<LorcanaCard>("character");
+      const isAction = isCardOfType<LorcanaCard>("action");
+
+      const character: LorcanaCard = {
+        id: "mickey-1",
+        name: "Mickey Mouse - Brave Little Tailor",
+        type: "character",
+        basePower: 4,
+      };
+
+      const action: LorcanaCard = {
+        id: "action-1",
+        name: "Be Prepared",
+        type: "action",
+      };
+
+      expect(isCharacter(character)).toBe(true);
+      expect(isCharacter(action)).toBe(false);
+      expect(isAction(action)).toBe(true);
+      expect(isAction(character)).toBe(false);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle cards with missing type field", () => {
+      const isCreature = isCardOfType("creature");
+      const cardWithoutType = { id: "1", name: "Card" } as CardDefinition;
+
+      expect(isCreature(cardWithoutType)).toBe(false);
+    });
+
+    it("should handle empty strings", () => {
+      const isEmpty = isCardOfType("");
+      const emptyCard: CardDefinition = {
+        id: "1",
+        name: "Card",
+        type: "",
+      };
+      const normalCard: CardDefinition = {
+        id: "2",
+        name: "Card",
+        type: "creature",
+      };
+
+      expect(isEmpty(emptyCard)).toBe(true);
+      expect(isEmpty(normalCard)).toBe(false);
+    });
+
+    it("should be case-sensitive", () => {
+      const isCreature = isCardOfType("creature");
+      const uppercaseCard: CardDefinition = {
+        id: "1",
+        name: "Card",
+        type: "Creature", // uppercase C
+      };
+      const lowercaseCard: CardDefinition = {
+        id: "2",
+        name: "Card",
+        type: "creature",
+      };
+
+      expect(isCreature(uppercaseCard)).toBe(false);
+      expect(isCreature(lowercaseCard)).toBe(true);
+    });
+  });
+
+  describe("performance", () => {
+    it("should be efficient for large arrays", () => {
+      const cards: CardDefinition[] = Array.from({ length: 10000 }, (_, i) => ({
+        id: `card-${i}`,
+        name: `Card ${i}`,
+        type: i % 3 === 0 ? "creature" : i % 3 === 1 ? "instant" : "sorcery",
+      }));
+
+      const isCreature = isCardOfType("creature");
+
+      const startTime = performance.now();
+      const creatures = cards.filter(isCreature);
+      const endTime = performance.now();
+
+      expect(creatures.length).toBeGreaterThan(0);
+      // Should complete in reasonable time (< 1000ms for 10k cards, higher threshold for CI parallel execution)
+      expect(endTime - startTime).toBeLessThan(1000);
+    });
+  });
+});

package/src/validation/card-type-guards.ts

@@ -0,0 +1,179 @@
+/**
+ * Card-specific type guard utilities
+ *
+ * Provides convenient type guards for filtering and narrowing card types
+ * in a type-safe manner.
+ */
+
+import type { CardDefinition } from "../cards/card-definition";
+import { createTypeGuard } from "./type-guard-builder";
+
+/**
+ * Creates a type guard for checking if a card is of a specific type
+ *
+ * This is a specialized version of createTypeGuard optimized for card definitions.
+ * It provides better ergonomics for the common use case of filtering cards by type.
+ *
+ * @template T - The card type (extends CardDefinition)
+ * @param cardType - The type value to check against
+ * @returns A type guard function that checks if a card matches the type
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const isCreature = isCardOfType("creature");
+ * const creature: CardDefinition = { id: "1", name: "Dragon", type: "creature" };
+ * console.log(isCreature(creature)); // true
+ *
+ * // Filtering arrays
+ * const cards: CardDefinition[] = [...];
+ * const creatures = cards.filter(isCardOfType("creature"));
+ *
+ * // Type narrowing in conditionals
+ * if (isCardOfType("creature")(card)) {
+ *   // TypeScript knows card.type is "creature" here
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Game-specific types
+ * type GundamCard = CardDefinition & {
+ *   type: "unit" | "command" | "character" | "base";
+ * };
+ *
+ * const isUnit = isCardOfType<GundamCard>("unit");
+ * const gundamCard: GundamCard = { id: "1", name: "Gundam", type: "unit" };
+ * console.log(isUnit(gundamCard)); // true
+ * ```
+ */
+export function isCardOfType<T extends CardDefinition = CardDefinition>(
+  cardType: T["type"],
+): (card: T) => card is T & { type: typeof cardType } {
+  return createTypeGuard<T, "type", T["type"]>("type", cardType);
+}
+
+/**
+ * Creates a type guard for checking if a card has a specific field value
+ *
+ * This is a more generic version that works with any card field, not just type.
+ * Useful for filtering by other properties like rarity, set, or custom fields.
+ *
+ * @template T - The card type (extends CardDefinition)
+ * @template K - The key of the field to check
+ * @template V - The value type to check against
+ *
+ * @param field - The field name to check
+ * @param value - The value to compare against
+ * @returns A type guard function
+ *
+ * @example
+ * ```typescript
+ * type ExtendedCard = CardDefinition & { rarity: "common" | "rare" | "mythic" };
+ *
+ * const isRare = isCardWithField<ExtendedCard, "rarity", "rare">("rarity", "rare");
+ * const rareCard: ExtendedCard = {
+ *   id: "1",
+ *   name: "Rare Dragon",
+ *   type: "creature",
+ *   rarity: "rare"
+ * };
+ *
+ * console.log(isRare(rareCard)); // true
+ * ```
+ */
+export function isCardWithField<
+  T extends CardDefinition,
+  K extends keyof T,
+  V extends T[K],
+>(field: K, value: V): (card: T) => card is T & Record<K, V> {
+  return createTypeGuard<T, K, V>(field, value);
+}
+
+/**
+ * Combines multiple type guards with AND logic
+ *
+ * Returns a type guard that passes only if all provided type guards pass.
+ * Useful for filtering cards that match multiple criteria.
+ *
+ * @template T - The object type to guard
+ * @param guards - Array of type guard functions to combine
+ * @returns A combined type guard that checks all conditions
+ *
+ * @example
+ * ```typescript
+ * type Card = CardDefinition & {
+ *   type: string;
+ *   rarity: string;
+ * };
+ *
+ * const isCreature = isCardOfType<Card>("creature");
+ * const isRare = isCardWithField<Card, "rarity", "rare">("rarity", "rare");
+ * const isRareCreature = combineTypeGuards([isCreature, isRare]);
+ *
+ * const cards: Card[] = [...];
+ * const rareCreatures = cards.filter(isRareCreature);
+ * ```
+ */
+export function combineTypeGuards<T>(
+  guards: Array<(obj: T) => boolean>,
+): (obj: T) => obj is T {
+  return (obj: T): obj is T => {
+    return guards.every((guard) => guard(obj));
+  };
+}
+
+/**
+ * Combines multiple type guards with OR logic
+ *
+ * Returns a type guard that passes if any of the provided type guards pass.
+ * Useful for filtering cards that match any of several criteria.
+ *
+ * @template T - The object type to guard
+ * @param guards - Array of type guard functions to combine
+ * @returns A combined type guard that checks any condition
+ *
+ * @example
+ * ```typescript
+ * const isCreature = isCardOfType("creature");
+ * const isInstant = isCardOfType("instant");
+ * const isSpell = combineTypeGuardsOr([isCreature, isInstant]);
+ *
+ * const cards: CardDefinition[] = [...];
+ * const spells = cards.filter(isSpell);
+ * ```
+ */
+export function combineTypeGuardsOr<T>(
+  guards: Array<(obj: T) => boolean>,
+): (obj: T) => obj is T {
+  return (obj: T): obj is T => {
+    return guards.some((guard) => guard(obj));
+  };
+}
+
+/**
+ * Negates a type guard
+ *
+ * Returns a type guard that passes when the provided type guard fails.
+ * Useful for filtering cards that don't match a specific criterion.
+ *
+ * @template T - The object type to guard
+ * @param guard - The type guard to negate
+ * @returns A negated type guard
+ *
+ * @example
+ * ```typescript
+ * const isCreature = isCardOfType("creature");
+ * const isNotCreature = negateTypeGuard(isCreature);
+ *
+ * const cards: CardDefinition[] = [...];
+ * const nonCreatures = cards.filter(isNotCreature);
+ * ```
+ */
+export function negateTypeGuard<T>(
+  guard: (obj: T) => boolean,
+): (obj: T) => obj is T {
+  return (obj: T): obj is T => {
+    return !guard(obj);
+  };
+}

package/src/validation/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Validation utilities for @drmxrcy/tcg-core
+ *
+ * This module provides type guards, validators, and schema builders
+ * for runtime validation of cards, moves, and game states.
+ *
+ * @module validation
+ */
+
+// Card-specific type guards
+export {
+  combineTypeGuards,
+  combineTypeGuardsOr,
+  isCardOfType,
+  isCardWithField,
+  negateTypeGuard,
+} from "./card-type-guards";
+// Zod schema builders
+export {
+  composeSchemas,
+  createArraySchema,
+  createCardSchema,
+  createDiscriminatedUnion,
+  createMultiRefinedSchema,
+  createOptionalSchema,
+  createRecordSchema,
+  createRefinedSchema,
+  createStrictSchema,
+  extendSchema,
+  mergeSchemas,
+} from "./schema-builders";
+// Type guard builder
+export { createTypeGuard } from "./type-guard-builder";
+// Validator builder
+export {
+  createValidator,
+  type ValidationResult,
+  type Validator,
+  ValidatorBuilder,
+} from "./validator-builder";