@drmxrcy/tcg-core 0.0.0-202602060542

package/src/validation/validator-builder.test.ts

@@ -0,0 +1,375 @@
+import { describe, expect, it } from "bun:test";
+import { ValidatorBuilder } from "./validator-builder";
+
+describe("ValidatorBuilder", () => {
+  describe("required validation", () => {
+    it("should validate required fields", () => {
+      const validator = new ValidatorBuilder<{ name: string }>()
+        .required("name", "Name is required")
+        .build();
+
+      const validResult = validator.validate({ name: "Test" });
+      expect(validResult.success).toBe(true);
+      if (validResult.success) {
+        expect(validResult.data).toEqual({ name: "Test" });
+      }
+
+      const invalidResult = validator.validate({ name: "" });
+      expect(invalidResult.success).toBe(false);
+      if (!invalidResult.success) {
+        expect(invalidResult.errors).toContain("Name is required");
+      }
+    });
+
+    it("should validate multiple required fields", () => {
+      const validator = new ValidatorBuilder<{ name: string; type: string }>()
+        .required("name", "Name is required")
+        .required("type", "Type is required")
+        .build();
+
+      const validResult = validator.validate({
+        name: "Test",
+        type: "creature",
+      });
+      expect(validResult.success).toBe(true);
+
+      const invalidResult = validator.validate({ name: "", type: "" });
+      expect(invalidResult.success).toBe(false);
+      if (!invalidResult.success) {
+        expect(invalidResult.errors).toHaveLength(2);
+      }
+    });
+  });
+
+  describe("type validation", () => {
+    it("should validate string types", () => {
+      const validator = new ValidatorBuilder<{ name: string }>()
+        .type("name", "string", "Name must be a string")
+        .build();
+
+      const validResult = validator.validate({ name: "Test" });
+      expect(validResult.success).toBe(true);
+
+      const invalidResult = validator.validate({ name: 123 as any });
+      expect(invalidResult.success).toBe(false);
+      if (!invalidResult.success) {
+        expect(invalidResult.errors).toContain("Name must be a string");
+      }
+    });
+
+    it("should validate number types", () => {
+      const validator = new ValidatorBuilder<{ power: number }>()
+        .type("power", "number", "Power must be a number")
+        .build();
+
+      const validResult = validator.validate({ power: 5 });
+      expect(validResult.success).toBe(true);
+
+      const invalidResult = validator.validate({ power: "5" as any });
+      expect(invalidResult.success).toBe(false);
+      if (!invalidResult.success) {
+        expect(invalidResult.errors).toContain("Power must be a number");
+      }
+    });
+
+    it("should validate boolean types", () => {
+      const validator = new ValidatorBuilder<{ enabled: boolean }>()
+        .type("enabled", "boolean", "Enabled must be a boolean")
+        .build();
+
+      const validResult = validator.validate({ enabled: true });
+      expect(validResult.success).toBe(true);
+
+      const invalidResult = validator.validate({ enabled: "true" as any });
+      expect(invalidResult.success).toBe(false);
+    });
+  });
+
+  describe("min/max validation", () => {
+    it("should validate minimum values for numbers", () => {
+      const validator = new ValidatorBuilder<{ power: number }>()
+        .min("power", 0, "Power must be at least 0")
+        .build();
+
+      const validResult = validator.validate({ power: 5 });
+      expect(validResult.success).toBe(true);
+
+      const invalidResult = validator.validate({ power: -1 });
+      expect(invalidResult.success).toBe(false);
+      if (!invalidResult.success) {
+        expect(invalidResult.errors).toContain("Power must be at least 0");
+      }
+    });
+
+    it("should validate maximum values for numbers", () => {
+      const validator = new ValidatorBuilder<{ power: number }>()
+        .max("power", 10, "Power must be at most 10")
+        .build();
+
+      const validResult = validator.validate({ power: 5 });
+      expect(validResult.success).toBe(true);
+
+      const invalidResult = validator.validate({ power: 15 });
+      expect(invalidResult.success).toBe(false);
+      if (!invalidResult.success) {
+        expect(invalidResult.errors).toContain("Power must be at most 10");
+      }
+    });
+
+    it("should validate min and max together", () => {
+      const validator = new ValidatorBuilder<{ power: number }>()
+        .min("power", 0, "Power must be at least 0")
+        .max("power", 10, "Power must be at most 10")
+        .build();
+
+      expect(validator.validate({ power: 5 }).success).toBe(true);
+      expect(validator.validate({ power: 0 }).success).toBe(true);
+      expect(validator.validate({ power: 10 }).success).toBe(true);
+      expect(validator.validate({ power: -1 }).success).toBe(false);
+      expect(validator.validate({ power: 11 }).success).toBe(false);
+    });
+
+    it("should validate string length with min", () => {
+      const validator = new ValidatorBuilder<{ name: string }>()
+        .min("name", 3, "Name must be at least 3 characters")
+        .build();
+
+      expect(validator.validate({ name: "Test" }).success).toBe(true);
+      expect(validator.validate({ name: "Hi" }).success).toBe(false);
+    });
+
+    it("should validate string length with max", () => {
+      const validator = new ValidatorBuilder<{ name: string }>()
+        .max("name", 10, "Name must be at most 10 characters")
+        .build();
+
+      expect(validator.validate({ name: "Short" }).success).toBe(true);
+      expect(validator.validate({ name: "Very Long Name" }).success).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("custom validation", () => {
+    it("should support custom validation functions", () => {
+      const validator = new ValidatorBuilder<{ email: string }>()
+        .custom(
+          "email",
+          (value) => typeof value === "string" && value.includes("@"),
+          "Email must contain @",
+        )
+        .build();
+
+      const validResult = validator.validate({ email: "test@example.com" });
+      expect(validResult.success).toBe(true);
+
+      const invalidResult = validator.validate({ email: "invalid-email" });
+      expect(invalidResult.success).toBe(false);
+      if (!invalidResult.success) {
+        expect(invalidResult.errors).toContain("Email must contain @");
+      }
+    });
+
+    it("should support multiple custom validators on the same field", () => {
+      const validator = new ValidatorBuilder<{ password: string }>()
+        .custom(
+          "password",
+          (value) => typeof value === "string" && value.length >= 8,
+          "Password must be at least 8 characters",
+        )
+        .custom(
+          "password",
+          (value) => typeof value === "string" && /[A-Z]/.test(value),
+          "Password must contain an uppercase letter",
+        )
+        .build();
+
+      expect(validator.validate({ password: "Password1" }).success).toBe(true);
+      expect(validator.validate({ password: "short" }).success).toBe(false);
+      expect(validator.validate({ password: "lowercase1" }).success).toBe(
+        false,
+      );
+    });
+  });
+
+  describe("fluent API", () => {
+    it("should chain multiple validations", () => {
+      const validator = new ValidatorBuilder<{
+        name: string;
+        power: number;
+        type: string;
+      }>()
+        .required("name", "Name is required")
+        .type("name", "string", "Name must be a string")
+        .min("name", 1, "Name must not be empty")
+        .max("name", 50, "Name must be at most 50 characters")
+        .required("power", "Power is required")
+        .type("power", "number", "Power must be a number")
+        .min("power", 0, "Power must be non-negative")
+        .max("power", 100, "Power must be at most 100")
+        .required("type", "Type is required")
+        .build();
+
+      const validResult = validator.validate({
+        name: "Dragon",
+        power: 50,
+        type: "creature",
+      });
+      expect(validResult.success).toBe(true);
+
+      const invalidResult = validator.validate({
+        name: "",
+        power: 150,
+        type: "",
+      });
+      expect(invalidResult.success).toBe(false);
+    });
+  });
+
+  describe("error collection", () => {
+    it("should collect all validation errors", () => {
+      const validator = new ValidatorBuilder<{
+        name: string;
+        power: number;
+        type: string;
+      }>()
+        .required("name", "Name is required")
+        .required("power", "Power is required")
+        .required("type", "Type is required")
+        .build();
+
+      const result = validator.validate({
+        name: "",
+        power: 0,
+        type: "",
+      });
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        expect(result.errors.length).toBeGreaterThan(0);
+      }
+    });
+
+    it("should stop at first error when configured", () => {
+      const validator = new ValidatorBuilder<{
+        name: string;
+        power: number;
+      }>({ abortEarly: true })
+        .required("name", "Name is required")
+        .required("power", "Power is required")
+        .build();
+
+      const result = validator.validate({
+        name: "",
+        power: 0,
+      });
+
+      expect(result.success).toBe(false);
+      if (!result.success) {
+        // With abortEarly, should only have one error
+        expect(result.errors).toHaveLength(1);
+      }
+    });
+  });
+
+  describe("complex object validation", () => {
+    it("should validate nested object structures", () => {
+      type Card = {
+        name: string;
+        metadata: {
+          version: number;
+          category: string;
+        };
+      };
+
+      const validator = new ValidatorBuilder<Card>()
+        .required("name", "Name is required")
+        .custom(
+          "metadata",
+          (value) => typeof value === "object" && value !== null,
+          "Metadata is required",
+        )
+        .build();
+
+      const validResult = validator.validate({
+        name: "Dragon",
+        metadata: { version: 1, category: "creature" },
+      });
+      expect(validResult.success).toBe(true);
+    });
+
+    it("should validate arrays", () => {
+      type Card = {
+        abilities: string[];
+      };
+
+      const validator = new ValidatorBuilder<Card>()
+        .custom(
+          "abilities",
+          (value) => Array.isArray(value) && value.length > 0,
+          "Must have at least one ability",
+        )
+        .build();
+
+      expect(
+        validator.validate({
+          abilities: ["Flying", "Haste"],
+        }).success,
+      ).toBe(true);
+
+      expect(
+        validator.validate({
+          abilities: [],
+        }).success,
+      ).toBe(false);
+    });
+  });
+
+  describe("reusability", () => {
+    it("should allow reusing validators", () => {
+      const cardValidator = new ValidatorBuilder<{
+        name: string;
+        type: string;
+      }>()
+        .required("name", "Name is required")
+        .required("type", "Type is required")
+        .build();
+
+      const card1 = { name: "Dragon", type: "creature" };
+      const card2 = { name: "Bolt", type: "instant" };
+      const card3 = { name: "", type: "" };
+
+      expect(cardValidator.validate(card1).success).toBe(true);
+      expect(cardValidator.validate(card2).success).toBe(true);
+      expect(cardValidator.validate(card3).success).toBe(false);
+    });
+  });
+
+  describe("performance", () => {
+    it("should validate efficiently", () => {
+      const validator = new ValidatorBuilder<{
+        name: string;
+        power: number;
+        type: string;
+      }>()
+        .required("name", "Name is required")
+        .type("name", "string", "Name must be a string")
+        .required("power", "Power is required")
+        .type("power", "number", "Power must be a number")
+        .min("power", 0, "Power must be non-negative")
+        .required("type", "Type is required")
+        .build();
+
+      const card = { name: "Dragon", power: 5, type: "creature" };
+
+      const startTime = performance.now();
+      for (let i = 0; i < 10000; i++) {
+        validator.validate(card);
+      }
+      const endTime = performance.now();
+
+      // Should complete in reasonable time (< 1000ms for 10k validations, higher threshold for CI parallel execution)
+      expect(endTime - startTime).toBeLessThan(1000);
+    });
+  });
+});

package/src/validation/validator-builder.ts

@@ -0,0 +1,273 @@
+/**
+ * Validator builder for creating fluent validation rules
+ *
+ * Provides a chainable API for building complex validation logic
+ * without external dependencies like Zod, useful for runtime validation.
+ */
+
+/**
+ * Validation rule function type
+ */
+type ValidationRule<T> = (value: T) => boolean;
+
+/**
+ * Validation error with field and message
+ */
+interface ValidationError {
+  field: string;
+  message: string;
+}
+
+/**
+ * Validation result - success with data or failure with errors
+ */
+export type ValidationResult<T> =
+  | { success: true; data: T }
+  | { success: false; errors: string[] };
+
+/**
+ * Validator function type
+ */
+export interface Validator<T> {
+  validate: (data: T) => ValidationResult<T>;
+}
+
+/**
+ * Options for validator builder
+ */
+interface ValidatorBuilderOptions {
+  /**
+   * If true, stops validation at the first error
+   * If false, collects all errors
+   */
+  abortEarly?: boolean;
+}
+
+/**
+ * Internal validation rule with metadata
+ */
+interface ValidationRuleWithMetadata<T> {
+  field: keyof T;
+  rule: ValidationRule<unknown>;
+  message: string;
+}
+
+/**
+ * ValidatorBuilder provides a fluent API for building validation rules
+ *
+ * @template T - The type of object to validate
+ *
+ * @example
+ * ```typescript
+ * const validator = new ValidatorBuilder<{ name: string; power: number }>()
+ *   .required("name", "Name is required")
+ *   .type("name", "string", "Name must be a string")
+ *   .min("name", 1, "Name must not be empty")
+ *   .required("power", "Power is required")
+ *   .type("power", "number", "Power must be a number")
+ *   .min("power", 0, "Power must be non-negative")
+ *   .build();
+ *
+ * const result = validator.validate({ name: "Dragon", power: 5 });
+ * if (result.success) {
+ *   console.log("Valid:", result.data);
+ * } else {
+ *   console.error("Errors:", result.errors);
+ * }
+ * ```
+ */
+export class ValidatorBuilder<T extends Record<string, unknown>> {
+  private rules: ValidationRuleWithMetadata<T>[] = [];
+  private options: ValidatorBuilderOptions;
+
+  constructor(options: ValidatorBuilderOptions = {}) {
+    this.options = {
+      abortEarly: false,
+      ...options,
+    };
+  }
+
+  /**
+   * Validates that a field is required (not empty/null/undefined)
+   *
+   * @param field - The field to validate
+   * @param message - Error message if validation fails
+   * @returns This builder instance for chaining
+   */
+  required<K extends keyof T>(field: K, message: string): this {
+    this.rules.push({
+      field,
+      rule: (value: unknown) => {
+        if (typeof value === "string") {
+          return value.trim().length > 0;
+        }
+        if (typeof value === "number") {
+          return true; // Numbers are always considered "present"
+        }
+        return value !== null && value !== undefined;
+      },
+      message,
+    });
+    return this;
+  }
+
+  /**
+   * Validates that a field is of a specific type
+   *
+   * @param field - The field to validate
+   * @param expectedType - The expected type ("string", "number", "boolean", "object")
+   * @param message - Error message if validation fails
+   * @returns This builder instance for chaining
+   */
+  type<K extends keyof T>(
+    field: K,
+    expectedType: "string" | "number" | "boolean" | "object",
+    message: string,
+  ): this {
+    this.rules.push({
+      field,
+      rule: (value: unknown) => typeof value === expectedType,
+      message,
+    });
+    return this;
+  }
+
+  /**
+   * Validates that a numeric field or string length is at least a minimum value
+   *
+   * @param field - The field to validate
+   * @param minValue - The minimum value (for numbers) or length (for strings)
+   * @param message - Error message if validation fails
+   * @returns This builder instance for chaining
+   */
+  min<K extends keyof T>(field: K, minValue: number, message: string): this {
+    this.rules.push({
+      field,
+      rule: (value: unknown) => {
+        if (typeof value === "number") {
+          return value >= minValue;
+        }
+        if (typeof value === "string") {
+          return value.length >= minValue;
+        }
+        return false;
+      },
+      message,
+    });
+    return this;
+  }
+
+  /**
+   * Validates that a numeric field or string length is at most a maximum value
+   *
+   * @param field - The field to validate
+   * @param maxValue - The maximum value (for numbers) or length (for strings)
+   * @param message - Error message if validation fails
+   * @returns This builder instance for chaining
+   */
+  max<K extends keyof T>(field: K, maxValue: number, message: string): this {
+    this.rules.push({
+      field,
+      rule: (value: unknown) => {
+        if (typeof value === "number") {
+          return value <= maxValue;
+        }
+        if (typeof value === "string") {
+          return value.length <= maxValue;
+        }
+        return false;
+      },
+      message,
+    });
+    return this;
+  }
+
+  /**
+   * Adds a custom validation rule
+   *
+   * @param field - The field to validate
+   * @param rule - Custom validation function that returns true if valid
+   * @param message - Error message if validation fails
+   * @returns This builder instance for chaining
+   */
+  custom<K extends keyof T>(
+    field: K,
+    rule: (value: T[K]) => boolean,
+    message: string,
+  ): this {
+    this.rules.push({
+      field,
+      rule: rule as ValidationRule<unknown>,
+      message,
+    });
+    return this;
+  }
+
+  /**
+   * Builds the validator from the accumulated rules
+   *
+   * @returns A validator object with a validate method
+   */
+  build(): Validator<T> {
+    const rules = [...this.rules];
+    const abortEarly = this.options.abortEarly;
+
+    return {
+      validate: (data: T): ValidationResult<T> => {
+        const errors: string[] = [];
+
+        for (const rule of rules) {
+          const fieldValue = data[rule.field];
+          const isValid = rule.rule(fieldValue);
+
+          if (!isValid) {
+            errors.push(rule.message);
+
+            if (abortEarly) {
+              return {
+                success: false,
+                errors,
+              };
+            }
+          }
+        }
+
+        if (errors.length > 0) {
+          return {
+            success: false,
+            errors,
+          };
+        }
+
+        return {
+          success: true,
+          data,
+        };
+      },
+    };
+  }
+}
+
+/**
+ * Helper function to create a validator with a more functional style
+ *
+ * @template T - The type of object to validate
+ * @param builderFn - Function that receives a builder and returns it with rules applied
+ * @returns A validator object
+ *
+ * @example
+ * ```typescript
+ * const validator = createValidator<{ name: string; power: number }>(builder =>
+ *   builder
+ *     .required("name", "Name is required")
+ *     .min("power", 0, "Power must be non-negative")
+ * );
+ * ```
+ */
+export function createValidator<T extends Record<string, unknown>>(
+  builderFn: (builder: ValidatorBuilder<T>) => ValidatorBuilder<T>,
+  options?: ValidatorBuilderOptions,
+): Validator<T> {
+  const builder = new ValidatorBuilder<T>(options);
+  return builderFn(builder).build();
+}

package/src/zones/index.ts

@@ -0,0 +1,28 @@
+export type { CardZoneConfig, Zone, ZoneVisibility } from "./zone";
+export { createZone } from "./zone-factory";
+export {
+  addCard,
+  addCardToBottom,
+  addCardToTop,
+  clearZone,
+  draw,
+  findCardInZones,
+  getBottomCard,
+  getCardsInZone,
+  getTopCard,
+  getZoneSize,
+  isCardInZone,
+  mill,
+  moveCard,
+  peek,
+  removeCard,
+  reveal,
+  search,
+  shuffle,
+} from "./zone-operations";
+export {
+  createPlayerZones,
+  getCardZone,
+  moveCardInState,
+} from "./zone-state-helpers";
+export { filterZoneByVisibility } from "./zone-visibility";