@drmxrcy/tcg-core 0.0.0-202602060542

package/src/validation/schema-builders.ts

@@ -0,0 +1,345 @@
+/**
+ * Zod schema composition utilities for building complex validation schemas
+ *
+ * Provides helper functions for composing, extending, and merging Zod schemas
+ * in a type-safe and reusable way.
+ */
+
+import { type ZodObject, type ZodRawShape, type ZodTypeAny, z } from "zod";
+
+/**
+ * Creates a card schema from a shape object
+ *
+ * This is a thin wrapper around z.object() that provides better semantics
+ * for card-related schemas and can be extended with additional features.
+ *
+ * @param shape - The shape of the schema
+ * @returns A Zod object schema
+ *
+ * @example
+ * ```typescript
+ * const cardSchema = createCardSchema({
+ *   id: z.string(),
+ *   name: z.string(),
+ *   type: z.string(),
+ *   basePower: z.number().optional(),
+ * });
+ *
+ * type Card = z.infer<typeof cardSchema>;
+ * ```
+ */
+export function createCardSchema<T extends ZodRawShape>(
+  shape: T,
+): ZodObject<T> {
+  return z.object(shape);
+}
+
+/**
+ * Extends a base schema with additional fields
+ *
+ * Creates a new schema that includes all fields from the base schema
+ * plus the new fields from the extension.
+ *
+ * @param baseSchema - The base schema to extend
+ * @param extension - Additional fields to add
+ * @returns A new schema with combined fields
+ *
+ * @example
+ * ```typescript
+ * const baseCardSchema = createCardSchema({
+ *   id: z.string(),
+ *   name: z.string(),
+ * });
+ *
+ * const creatureSchema = extendSchema(baseCardSchema, {
+ *   power: z.number(),
+ *   toughness: z.number(),
+ * });
+ * ```
+ */
+export function extendSchema<T extends ZodRawShape, E extends ZodRawShape>(
+  baseSchema: ZodObject<T>,
+  extension: E,
+): ZodObject<any> {
+  return baseSchema.extend(extension) as ZodObject<any>;
+}
+
+/**
+ * Merges multiple schemas into one
+ *
+ * Combines all fields from all provided schemas into a single schema.
+ * Later schemas can override fields from earlier schemas.
+ *
+ * @param schemas - Schemas to merge (at least 2)
+ * @returns A new schema with all fields merged
+ *
+ * @example
+ * ```typescript
+ * const baseSchema = createCardSchema({ id: z.string() });
+ * const typeSchema = createCardSchema({ type: z.string() });
+ * const statsSchema = createCardSchema({ power: z.number() });
+ *
+ * const fullSchema = mergeSchemas(baseSchema, typeSchema, statsSchema);
+ * ```
+ */
+export function mergeSchemas<T extends ZodRawShape, U extends ZodRawShape>(
+  schema1: ZodObject<T>,
+  schema2: ZodObject<U>,
+): ZodObject<any>;
+
+export function mergeSchemas<
+  T extends ZodRawShape,
+  U extends ZodRawShape,
+  V extends ZodRawShape,
+>(
+  schema1: ZodObject<T>,
+  schema2: ZodObject<U>,
+  schema3: ZodObject<V>,
+): ZodObject<any>;
+
+export function mergeSchemas<
+  T extends ZodRawShape,
+  U extends ZodRawShape,
+  V extends ZodRawShape,
+  W extends ZodRawShape,
+>(
+  schema1: ZodObject<T>,
+  schema2: ZodObject<U>,
+  schema3: ZodObject<V>,
+  schema4: ZodObject<W>,
+): ZodObject<any>;
+
+export function mergeSchemas(
+  ...schemas: ZodObject<ZodRawShape>[]
+): ZodObject<any> {
+  if (schemas.length < 2) {
+    throw new Error("mergeSchemas requires at least 2 schemas");
+  }
+
+  return schemas.reduce((acc, schema) => acc.merge(schema)) as ZodObject<any>;
+}
+
+/**
+ * Composes multiple schemas by intersecting them
+ *
+ * Creates a schema that validates against all provided schemas.
+ * This is useful when you want to ensure data matches multiple independent schemas.
+ *
+ * @param schemas - Array of schemas to compose
+ * @returns A composed schema
+ *
+ * @example
+ * ```typescript
+ * const hasId = z.object({ id: z.string() });
+ * const hasName = z.object({ name: z.string() });
+ * const hasType = z.object({ type: z.string() });
+ *
+ * const fullSchema = composeSchemas([hasId, hasName, hasType]);
+ * ```
+ */
+export function composeSchemas(schemas: ZodTypeAny[]): ZodTypeAny {
+  if (schemas.length === 0) {
+    throw new Error("composeSchemas requires at least 1 schema");
+  }
+
+  if (schemas.length === 1) {
+    return schemas[0];
+  }
+
+  // Use merge for object schemas
+  return schemas.reduce((acc: ZodTypeAny, schema: ZodTypeAny): ZodTypeAny => {
+    if (acc instanceof z.ZodObject && schema instanceof z.ZodObject) {
+      return acc.merge(schema) as ZodTypeAny;
+    }
+    return z.intersection(acc, schema);
+  }) as ZodTypeAny;
+}
+
+/**
+ * Makes all fields in a schema optional
+ *
+ * Creates a new schema where all fields from the original schema
+ * are optional. Useful for partial updates or patch operations.
+ *
+ * @param schema - The schema to make optional
+ * @returns A schema with all fields optional
+ *
+ * @example
+ * ```typescript
+ * const requiredSchema = createCardSchema({
+ *   id: z.string(),
+ *   name: z.string(),
+ *   type: z.string(),
+ * });
+ *
+ * const optionalSchema = createOptionalSchema(requiredSchema);
+ * // Now id, name, and type are all optional
+ * ```
+ */
+export function createOptionalSchema<T extends ZodRawShape>(
+  schema: ZodObject<T>,
+): ZodObject<{ [K in keyof T]: ZodTypeAny }> {
+  return schema.partial() as ZodObject<{ [K in keyof T]: ZodTypeAny }>;
+}
+
+/**
+ * Creates a strict schema that doesn't allow extra fields
+ *
+ * By default, Zod schemas allow extra fields. This function creates
+ * a schema that will reject objects with fields not defined in the schema.
+ *
+ * @param shape - The shape of the schema
+ * @returns A strict schema
+ *
+ * @example
+ * ```typescript
+ * const schema = createStrictSchema({
+ *   id: z.string(),
+ *   name: z.string(),
+ * });
+ *
+ * // This will fail because of the extra field
+ * schema.parse({ id: "1", name: "Card", extra: "not allowed" });
+ * ```
+ */
+export function createStrictSchema<T extends ZodRawShape>(
+  shape: T,
+): ZodObject<T> {
+  return z.object(shape).strict();
+}
+
+/**
+ * Creates a schema for validating arrays of items
+ *
+ * @param itemSchema - Schema for individual items
+ * @param options - Optional constraints (min, max length)
+ * @returns A schema for validating arrays
+ *
+ * @example
+ * ```typescript
+ * const cardSchema = createCardSchema({
+ *   id: z.string(),
+ *   name: z.string(),
+ * });
+ *
+ * const deckSchema = createArraySchema(cardSchema, { min: 40, max: 60 });
+ * ```
+ */
+export function createArraySchema<T extends ZodTypeAny>(
+  itemSchema: T,
+  options?: { min?: number; max?: number },
+): z.ZodArray<T> {
+  let arraySchema = z.array(itemSchema);
+
+  if (options?.min !== undefined) {
+    arraySchema = arraySchema.min(options.min);
+  }
+
+  if (options?.max !== undefined) {
+    arraySchema = arraySchema.max(options.max);
+  }
+
+  return arraySchema;
+}
+
+/**
+ * Creates a discriminated union schema
+ *
+ * Useful for validating objects that have different shapes based on a discriminator field.
+ *
+ * @param discriminator - The field that determines which schema to use
+ * @param schemas - Map of discriminator values to schemas
+ * @returns A discriminated union schema
+ *
+ * @example
+ * ```typescript
+ * const cardSchema = createDiscriminatedUnion("type", [
+ *   z.object({ type: z.literal("creature"), power: z.number() }),
+ *   z.object({ type: z.literal("instant"), damage: z.number() }),
+ * ]);
+ * ```
+ */
+export function createDiscriminatedUnion<K extends string>(
+  discriminator: K,
+  schemas: [ZodObject<any>, ZodObject<any>, ...ZodObject<any>[]],
+): z.ZodDiscriminatedUnion<K, any> {
+  return z.discriminatedUnion(discriminator, schemas as any);
+}
+
+/**
+ * Creates a record schema for dynamic key-value mappings
+ *
+ * @param keySchema - Schema for the keys
+ * @param valueSchema - Schema for the values
+ * @returns A record schema
+ *
+ * @example
+ * ```typescript
+ * // Map of player IDs to scores
+ * const scoresSchema = createRecordSchema(z.string(), z.number());
+ * ```
+ */
+export function createRecordSchema<
+  K extends z.ZodTypeAny,
+  V extends z.ZodTypeAny,
+>(keySchema: K, valueSchema: V): z.ZodRecord<K, V> {
+  return z.record(keySchema, valueSchema);
+}
+
+/**
+ * Creates a schema with custom refinements and error messages
+ *
+ * @param baseSchema - The base schema to refine
+ * @param refinement - Refinement function
+ * @param message - Error message if refinement fails
+ * @returns A refined schema
+ *
+ * @example
+ * ```typescript
+ * const powerSchema = z.number();
+ * const positivePowerSchema = createRefinedSchema(
+ *   powerSchema,
+ *   (val) => val > 0,
+ *   "Power must be positive"
+ * );
+ * ```
+ */
+export function createRefinedSchema<T extends ZodTypeAny>(
+  baseSchema: T,
+  refinement: (val: z.infer<T>) => boolean,
+  message: string,
+): z.ZodEffects<T> {
+  return baseSchema.refine(refinement, { message });
+}
+
+/**
+ * Creates a schema with multiple refinements
+ *
+ * @param baseSchema - The base schema to refine
+ * @param refinements - Array of refinements with messages
+ * @returns A refined schema
+ *
+ * @example
+ * ```typescript
+ * const passwordSchema = createMultiRefinedSchema(z.string(), [
+ *   { check: (val) => val.length >= 8, message: "Must be at least 8 characters" },
+ *   { check: (val) => /[A-Z]/.test(val), message: "Must contain uppercase" },
+ *   { check: (val) => /[0-9]/.test(val), message: "Must contain number" },
+ * ]);
+ * ```
+ */
+export function createMultiRefinedSchema<T extends ZodTypeAny>(
+  baseSchema: T,
+  refinements: Array<{
+    check: (val: z.infer<T>) => boolean;
+    message: string;
+  }>,
+): ZodTypeAny {
+  let schema: ZodTypeAny = baseSchema;
+
+  for (const { check, message } of refinements) {
+    schema = schema.refine(check, { message });
+  }
+
+  return schema;
+}

package/src/validation/type-guard-builder.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it } from "bun:test";
+import { createTypeGuard } from "./type-guard-builder";
+
+describe("createTypeGuard", () => {
+  describe("basic type guards", () => {
+    it("should create a type guard for a string field", () => {
+      type Card = { type: string; name: string };
+      const isCreature = createTypeGuard<Card, "type", "creature">(
+        "type",
+        "creature",
+      );
+
+      const creature: Card = { type: "creature", name: "Dragon" };
+      const instant: Card = { type: "instant", name: "Lightning Bolt" };
+
+      expect(isCreature(creature)).toBe(true);
+      expect(isCreature(instant)).toBe(false);
+    });
+
+    it("should create a type guard for a number field", () => {
+      type Item = { id: number; category: string };
+      const isItem42 = createTypeGuard<Item, "id", 42>("id", 42);
+
+      const item42: Item = { id: 42, category: "test" };
+      const item10: Item = { id: 10, category: "test" };
+
+      expect(isItem42(item42)).toBe(true);
+      expect(isItem42(item10)).toBe(false);
+    });
+
+    it("should create a type guard for a boolean field", () => {
+      type Config = { enabled: boolean; name: string };
+      const isEnabled = createTypeGuard<Config, "enabled", true>(
+        "enabled",
+        true,
+      );
+
+      const enabledConfig: Config = { enabled: true, name: "test" };
+      const disabledConfig: Config = { enabled: false, name: "test" };
+
+      expect(isEnabled(enabledConfig)).toBe(true);
+      expect(isEnabled(disabledConfig)).toBe(false);
+    });
+  });
+
+  describe("complex types", () => {
+    it("should work with union types", () => {
+      type Card = { type: "creature" | "instant" | "sorcery"; name: string };
+      const isCreature = createTypeGuard<Card, "type", "creature">(
+        "type",
+        "creature",
+      );
+      const isInstant = createTypeGuard<Card, "type", "instant">(
+        "type",
+        "instant",
+      );
+
+      const creature: Card = { type: "creature", name: "Dragon" };
+      const instant: Card = { type: "instant", name: "Lightning Bolt" };
+
+      expect(isCreature(creature)).toBe(true);
+      expect(isCreature(instant)).toBe(false);
+      expect(isInstant(instant)).toBe(true);
+      expect(isInstant(creature)).toBe(false);
+    });
+
+    it("should work with optional fields", () => {
+      type Card = { type?: string; name: string };
+      const isCreature = createTypeGuard<Card, "type", "creature">(
+        "type",
+        "creature",
+      );
+
+      const creature: Card = { type: "creature", name: "Dragon" };
+      const noType: Card = { name: "Unknown" };
+
+      expect(isCreature(creature)).toBe(true);
+      expect(isCreature(noType)).toBe(false);
+    });
+
+    it("should work with nested objects", () => {
+      type Card = {
+        metadata: {
+          category: string;
+          version: number;
+        };
+        name: string;
+      };
+      const isStandard = createTypeGuard<
+        Card,
+        "metadata",
+        { category: "standard"; version: 1 }
+      >("metadata", { category: "standard", version: 1 });
+
+      const standardCard: Card = {
+        metadata: { category: "standard", version: 1 },
+        name: "Card",
+      };
+      const modernCard: Card = {
+        metadata: { category: "modern", version: 1 },
+        name: "Card",
+      };
+
+      expect(isStandard(standardCard)).toBe(true);
+      expect(isStandard(modernCard)).toBe(false);
+    });
+  });
+
+  describe("type narrowing", () => {
+    it("should narrow types correctly in TypeScript", () => {
+      type Card = {
+        type: "creature" | "instant";
+        name: string;
+        power?: number;
+      };
+      const isCreature = createTypeGuard<Card, "type", "creature">(
+        "type",
+        "creature",
+      );
+
+      const card: Card = { type: "creature", name: "Dragon", power: 5 };
+
+      if (isCreature(card)) {
+        // TypeScript should know that card.type is "creature" here
+        const typeValue: "creature" = card.type;
+        expect(typeValue).toBe("creature");
+      }
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle null and undefined gracefully", () => {
+      type Card = { type: string | null | undefined; name: string };
+      const isCreature = createTypeGuard<Card, "type", "creature">(
+        "type",
+        "creature",
+      );
+
+      const nullCard: Card = { type: null, name: "Card" };
+      const undefinedCard: Card = { type: undefined, name: "Card" };
+      const validCard: Card = { type: "creature", name: "Card" };
+
+      expect(isCreature(nullCard)).toBe(false);
+      expect(isCreature(undefinedCard)).toBe(false);
+      expect(isCreature(validCard)).toBe(true);
+    });
+
+    it("should handle empty strings", () => {
+      type Card = { type: string; name: string };
+      const isEmpty = createTypeGuard<Card, "type", "">("type", "");
+
+      const emptyCard: Card = { type: "", name: "Card" };
+      const nonEmptyCard: Card = { type: "creature", name: "Card" };
+
+      expect(isEmpty(emptyCard)).toBe(true);
+      expect(isEmpty(nonEmptyCard)).toBe(false);
+    });
+
+    it("should handle objects without the specified field", () => {
+      type PartialCard = { name: string; type?: string };
+      const isCreature = createTypeGuard<PartialCard, "type", "creature">(
+        "type",
+        "creature",
+      );
+
+      const card: PartialCard = { name: "Card" };
+
+      expect(isCreature(card)).toBe(false);
+    });
+  });
+
+  describe("array values", () => {
+    it("should create a type guard for array field values", () => {
+      type Card = { types: string[]; name: string };
+      const hasCreatureTypes = createTypeGuard<Card, "types", string[]>(
+        "types",
+        ["creature", "dragon"],
+      );
+
+      const dragonCard: Card = {
+        types: ["creature", "dragon"],
+        name: "Dragon",
+      };
+      const goblinCard: Card = {
+        types: ["creature", "goblin"],
+        name: "Goblin",
+      };
+
+      expect(hasCreatureTypes(dragonCard)).toBe(true);
+      expect(hasCreatureTypes(goblinCard)).toBe(false);
+    });
+  });
+
+  describe("performance", () => {
+    it("should be efficient for multiple checks", () => {
+      type Card = { type: string; name: string };
+      const isCreature = createTypeGuard<Card, "type", "creature">(
+        "type",
+        "creature",
+      );
+
+      const creature: Card = { type: "creature", name: "Dragon" };
+      const instant: Card = { type: "instant", name: "Lightning Bolt" };
+
+      const startTime = performance.now();
+      for (let i = 0; i < 10000; i++) {
+        isCreature(creature);
+        isCreature(instant);
+      }
+      const endTime = performance.now();
+
+      // Should complete in reasonable time (< 1000ms for 20k checks, higher threshold for CI parallel execution)
+      expect(endTime - startTime).toBeLessThan(1000);
+    });
+  });
+});

package/src/validation/type-guard-builder.ts

@@ -0,0 +1,109 @@
+/**
+ * Type guard builder utilities for creating type narrowing functions
+ *
+ * These utilities help create type-safe predicates that TypeScript can use
+ * for type narrowing in conditional blocks.
+ */
+
+/**
+ * Creates a type guard function that checks if an object's field matches a specific value
+ *
+ * @template T - The object type to guard
+ * @template K - The key of the field to check (must be a key of T)
+ * @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 that narrows T based on the field value
+ *
+ * @example
+ * ```typescript
+ * type Card = { type: "creature" | "instant"; name: string };
+ * const isCreature = createTypeGuard<Card, "type", "creature">("type", "creature");
+ *
+ * const card: Card = { type: "creature", name: "Dragon" };
+ * if (isCreature(card)) {
+ *   // TypeScript knows card.type is "creature" here
+ *   console.log(card.type); // Type: "creature"
+ * }
+ * ```
+ */
+export function createTypeGuard<T, K extends keyof T, V extends T[K]>(
+  field: K,
+  value: V,
+): (obj: T) => obj is T & Record<K, V> {
+  return (obj: T): obj is T & Record<K, V> => {
+    // Handle null and undefined gracefully
+    if (obj === null || obj === undefined) {
+      return false;
+    }
+
+    const fieldValue = obj[field];
+
+    // Handle primitive comparisons
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+      // Deep equality check for objects
+      return deepEqual(fieldValue, value);
+    }
+
+    if (Array.isArray(value)) {
+      // Deep equality check for arrays
+      return deepEqual(fieldValue, value);
+    }
+
+    // Simple equality check for primitives
+    return fieldValue === value;
+  };
+}
+
+/**
+ * Deep equality comparison for objects and arrays
+ * Used internally by createTypeGuard for complex value comparisons
+ *
+ * @param a - First value to compare
+ * @param b - Second value to compare
+ * @returns true if values are deeply equal, false otherwise
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+  // Handle primitive types
+  if (a === b) {
+    return true;
+  }
+
+  // Handle null and undefined
+  if (a === null || b === null || a === undefined || b === undefined) {
+    return a === b;
+  }
+
+  // Handle different types
+  if (typeof a !== typeof b) {
+    return false;
+  }
+
+  // Handle arrays
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) {
+      return false;
+    }
+    return a.every((item, index) => deepEqual(item, b[index]));
+  }
+
+  // Handle objects
+  if (typeof a === "object" && typeof b === "object") {
+    const keysA = Object.keys(a as object);
+    const keysB = Object.keys(b as object);
+
+    if (keysA.length !== keysB.length) {
+      return false;
+    }
+
+    return keysA.every((key) =>
+      deepEqual(
+        (a as Record<string, unknown>)[key],
+        (b as Record<string, unknown>)[key],
+      ),
+    );
+  }
+
+  return false;
+}