@divmain/jdm-asm 0.2.1 → 0.2.3

package/tests/helpers/round-trip.ts

@@ -1,398 +0,0 @@
-/**
- * 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 });
-  };
-}