@divmain/jdm-asm 0.2.0

package/tests/helpers/round-trip.ts

@@ -0,0 +1,398 @@
+/**
+ * Round-trip testing utilities for marshaling/unmarshaling.
+ *
+ * These helpers verify that data can be marshaled to WASM memory format
+ * and unmarshaled back to the original JavaScript value without data loss.
+ *
+ * @module tests/helpers/round-trip
+ */
+
+import type { TSchema } from '@sinclair/typebox';
+import { expect } from 'vitest';
+import { flattenSchema, computeSchemaHash } from '../../src/compiler/schema';
+import { generateMarshalCode } from '../../src/compiler/marshal-gen';
+
+/**
+ * Type for the marshal function generated by generateMarshalCode.
+ *
+ * Generated code uses 3-arg signature (data, memory, allocate) for flexibility, while the
+ * exported runtime wrapper uses 2-arg signature (data, memory) with internal allocator.
+ * This separation allows testing the raw generated code without wrapper overhead.
+ */
+type GeneratedMarshalFn = (
+  data: Record<string, unknown>,
+  memory: WebAssembly.Memory,
+  allocate: (size: number) => number,
+) => number;
+
+type GeneratedUnmarshalFn = (ptr: number, memory: WebAssembly.Memory) => Record<string, unknown>;
+
+/**
+ * Load marshal and unmarshal functions from generated code string.
+ *
+ * This is a simplified version of loadGeneratedMarshaling from runtime.ts
+ * that correctly handles the 3-argument marshal function signature.
+ */
+function loadMarshalFunctions(code: string): {
+  marshal: GeneratedMarshalFn;
+  unmarshal: GeneratedUnmarshalFn;
+} {
+  // Generated code has exports for bundler usage, but we need plain functions for eval() in
+  // tests. We rename to avoid naming conflicts and preserve test isolation.
+  const cleanedCode = code
+    .replace(/^export function marshalInput/gm, 'function marshalInputHelper')
+    .replace(/^export function unmarshalOutput/gm, 'function unmarshalOutputHelper')
+    .replace(/^export const SCHEMA_HASH/gm, 'const SCHEMA_HASH')
+    .replace(/^export const INPUT_FIXED_SIZE/gm, 'const INPUT_FIXED_SIZE')
+    .replace(/^export const OUTPUT_FIXED_SIZE/gm, 'const OUTPUT_FIXED_SIZE')
+    .replace(/^export function writeString/gm, 'function writeStringHelper')
+    .replace(/^export function readString/gm, 'function readStringHelper')
+    .replace(/^export function writeArray/gm, 'function writeArrayHelper')
+    .replace(/^export function readArray/gm, 'function readArrayHelper')
+    .replace(/^export function calculateInputSize/gm, 'function calculateInputSizeHelper');
+
+  // Helper function to extract nested values
+  const helperCode = `
+    function getNestedValue(obj, path) {
+      const parts = path.split('.');
+      let current = obj;
+      for (const part of parts) {
+        if (current == null) return undefined;
+        if (typeof current !== 'object') return undefined;
+        current = current[part];
+      }
+      return current;
+    }
+  `;
+
+  const module: { marshalInput?: GeneratedMarshalFn; unmarshalOutput?: GeneratedUnmarshalFn } = {};
+
+  const setupFn = new Function(
+    'module',
+    helperCode +
+      cleanedCode +
+      `
+      module.marshalInput = marshalInputHelper;
+      module.unmarshalOutput = unmarshalOutputHelper;
+    `,
+  );
+
+  setupFn(module);
+
+  if (!module.marshalInput || !module.unmarshalOutput) {
+    throw new Error('Generated marshaling code did not export required functions');
+  }
+
+  return {
+    marshal: module.marshalInput,
+    unmarshal: module.unmarshalOutput,
+  };
+}
+
+/**
+ * Options for round-trip testing.
+ */
+export interface RoundTripOptions {
+  /**
+   * Custom equality comparison function.
+   * By default uses deep equality with floating point tolerance.
+   */
+  compare?: (expected: unknown, actual: unknown) => boolean;
+
+  /**
+   * Whether to log debug information on failure.
+   * @default false
+   */
+  debug?: boolean;
+
+  /**
+   * Custom memory size in bytes.
+   * @default 65536 (64KB)
+   */
+  memorySize?: number;
+}
+
+/**
+ * Result of a round-trip test.
+ */
+export interface RoundTripResult<T> {
+  /** The original value that was marshaled */
+  original: T;
+  /** The value after unmarshaling */
+  recovered: unknown;
+  /** Whether the round-trip was successful (values match) */
+  success: boolean;
+  /** Time taken to marshal in milliseconds */
+  marshalTime: number;
+  /** Time taken to unmarshal in milliseconds */
+  unmarshalTime: number;
+  /** Total bytes used in memory */
+  bytesUsed: number;
+}
+
+/**
+ * Test that a value can be marshaled and unmarshaled without data loss.
+ *
+ * This function marshals a value to WASM memory format using the generated
+ * marshaling code for the given schema, then unmarshals it back and verifies
+ * the result matches the original value.
+ *
+ * @param schema - TypeBox schema describing the value structure
+ * @param value - The value to test
+ * @param options - Optional configuration
+ * @throws AssertionError if the round-trip fails
+ *
+ * @example
+ * ```typescript
+ * import { Type } from '@sinclair/typebox';
+ * import { testMarshalRoundTrip } from './round-trip';
+ *
+ * // Test a simple object
+ * await testMarshalRoundTrip(
+ *   Type.Object({ name: Type.String(), age: Type.Number() }),
+ *   { name: 'Alice', age: 30 }
+ * );
+ *
+ * // Test with custom comparison
+ * await testMarshalRoundTrip(schema, value, {
+ *   compare: (a, b) => JSON.stringify(a) === JSON.stringify(b)
+ * });
+ * ```
+ */
+export async function testMarshalRoundTrip<T>(
+  schema: TSchema,
+  value: T,
+  options: RoundTripOptions = {},
+): Promise<void> {
+  const result = await executeRoundTrip(schema, value, options);
+
+  if (!result.success) {
+    const message = [
+      'Round-trip test failed:',
+      `  Original: ${JSON.stringify(result.original, null, 2)}`,
+      `  Recovered: ${JSON.stringify(result.recovered, null, 2)}`,
+    ].join('\n');
+
+    if (options.debug) {
+      console.error(message);
+    }
+
+    expect(result.recovered).toEqual(result.original);
+  }
+}
+
+/**
+ * Execute a round-trip test and return detailed results.
+ *
+ * Unlike `testMarshalRoundTrip`, this function does not throw on failure.
+ * Instead, it returns detailed results that can be used for debugging
+ * or custom assertions.
+ *
+ * @param schema - TypeBox schema describing the value structure
+ * @param value - The value to test
+ * @param options - Optional configuration
+ * @returns Detailed round-trip test results
+ *
+ * @example
+ * ```typescript
+ * const result = await executeRoundTrip(schema, complexValue);
+ * console.log(`Marshal time: ${result.marshalTime}ms`);
+ * console.log(`Memory used: ${result.bytesUsed} bytes`);
+ * if (!result.success) {
+ *   console.error('Mismatch:', result.original, result.recovered);
+ * }
+ * ```
+ */
+export async function executeRoundTrip<T>(
+  schema: TSchema,
+  value: T,
+  options: RoundTripOptions = {},
+): Promise<RoundTripResult<T>> {
+  const { memorySize = 65536 } = options;
+
+  // Generate marshaling code from schema
+  const layout = flattenSchema(schema);
+  const hash = computeSchemaHash(schema, schema);
+  const marshalCode = generateMarshalCode(layout, layout, hash);
+
+  // Load the generated functions
+  const { marshal, unmarshal } = loadMarshalFunctions(marshalCode);
+
+  // Create WASM memory
+  const memory = new WebAssembly.Memory({
+    initial: Math.ceil(memorySize / 65536),
+    maximum: 256,
+  });
+
+  // Simple bump allocator
+  // The 1024 offset reserves space for potential WASM static data (globals, tables, etc.)
+  // which typically occupy low memory addresses. Starting at 1KB provides safe separation.
+  let heapOffset = 1024; // Start after static data area
+  const allocate = (size: number): number => {
+    const ptr = heapOffset;
+    heapOffset += size;
+    return ptr;
+  };
+
+  // Marshal
+  const marshalStart = performance.now();
+  const ptr = marshal(value as Record<string, unknown>, memory, allocate);
+  const marshalTime = performance.now() - marshalStart;
+
+  // Unmarshal
+  const unmarshalStart = performance.now();
+  const recovered = unmarshal(ptr, memory);
+  const unmarshalTime = performance.now() - unmarshalStart;
+
+  // Compare
+  const compare = options.compare ?? deepEqual;
+  const success = compare(value, recovered);
+
+  return {
+    original: value,
+    recovered,
+    success,
+    marshalTime,
+    unmarshalTime,
+    bytesUsed: heapOffset,
+  };
+}
+
+/**
+ * Test multiple values with the same schema.
+ *
+ * Useful for testing various edge cases or data shapes with a single schema.
+ *
+ * @param schema - TypeBox schema describing the value structure
+ * @param values - Array of values to test
+ * @param options - Optional configuration
+ * @throws AssertionError if any round-trip fails
+ *
+ * @example
+ * ```typescript
+ * await testMarshalRoundTripBatch(
+ *   Type.Object({ x: Type.Number() }),
+ *   [
+ *     { x: 0 },
+ *     { x: -1 },
+ *     { x: Number.MAX_SAFE_INTEGER },
+ *     { x: 0.1 + 0.2 }, // floating point
+ *   ]
+ * );
+ * ```
+ */
+export async function testMarshalRoundTripBatch<T>(
+  schema: TSchema,
+  values: T[],
+  options: RoundTripOptions = {},
+): Promise<void> {
+  for (let i = 0; i < values.length; i++) {
+    try {
+      await testMarshalRoundTrip(schema, values[i], options);
+    } catch (error) {
+      throw new Error(
+        `Round-trip failed for value at index ${i}: ${JSON.stringify(values[i])}\n` +
+          (error instanceof Error ? error.message : String(error)),
+      );
+    }
+  }
+}
+
+/**
+ * Deep equality comparison with floating point tolerance.
+ *
+ * Handles:
+ * - Null/undefined
+ * - Primitives (with floating point tolerance for numbers)
+ * - Arrays (recursive comparison)
+ * - Objects (recursive comparison)
+ *
+ * @param a - First value
+ * @param b - Second value
+ * @returns true if values are equal
+ */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  // Handle null/undefined
+  if (a === b) {
+    return true;
+  }
+  if (a === null || b === null) {
+    return false;
+  }
+  if (a === undefined || b === undefined) {
+    return false;
+  }
+
+  // Handle different types
+  if (typeof a !== typeof b) {
+    return false;
+  }
+
+  // Handle numbers with floating point tolerance
+  if (typeof a === 'number' && typeof b === 'number') {
+    if (Number.isNaN(a) && Number.isNaN(b)) {
+      return true;
+    }
+    if (!Number.isFinite(a) || !Number.isFinite(b)) {
+      return a === b;
+    }
+
+    // Use relative tolerance for large numbers, absolute for small
+    const tolerance = 1e-14;
+    const diff = Math.abs(a - b);
+    const maxAbs = Math.max(Math.abs(a), Math.abs(b), 1);
+    return diff / maxAbs < tolerance || diff < Number.EPSILON;
+  }
+
+  // Handle arrays
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) {
+      return false;
+    }
+    if (a.length !== b.length) {
+      return false;
+    }
+    return a.every((val, i) => deepEqual(val, b[i]));
+  }
+
+  // Handle objects
+  if (typeof a === 'object' && typeof b === 'object') {
+    const aObj = a as Record<string, unknown>;
+    const bObj = b as Record<string, unknown>;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+
+    if (aKeys.length !== bKeys.length) {
+      return false;
+    }
+
+    return aKeys.every((key) => deepEqual(aObj[key], bObj[key]));
+  }
+
+  // Primitive comparison
+  return a === b;
+}
+
+/**
+ * Create a custom round-trip tester with preset options.
+ *
+ * Useful for creating test-specific testers with consistent configuration.
+ *
+ * @param defaultOptions - Default options for all tests
+ * @returns A tester function with preset options
+ *
+ * @example
+ * ```typescript
+ * const debugTester = createRoundTripTester({ debug: true });
+ *
+ * // Now all tests will log debug info
+ * await debugTester(schema, value);
+ * ```
+ */
+export function createRoundTripTester(
+  defaultOptions: RoundTripOptions = {},
+): <T>(schema: TSchema, value: T, options?: RoundTripOptions) => Promise<void> {
+  return async <T>(schema: TSchema, value: T, options: RoundTripOptions = {}): Promise<void> => {
+    return testMarshalRoundTrip(schema, value, { ...defaultOptions, ...options });
+  };
+}