@studio-foundation/ralph 0.3.0-beta.1

package/tests/loop.test.ts

@@ -0,0 +1,355 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ralph, type ExecutionContext } from '../src/loop.js';
+import { noDelay } from '../src/retry-strategy.js';
+
+describe('ralph loop', () => {
+  it('returns success on first attempt when valid', async () => {
+    const executor = vi.fn().mockResolvedValue('result');
+    const validator = vi.fn().mockReturnValue({ valid: true, errors: [], warnings: [] });
+
+    const result = await ralph({
+      executor,
+      validator,
+      maxAttempts: 3,
+      retryStrategy: noDelay()
+    });
+
+    expect(result.status).toBe('success');
+    expect(result.attempts).toBe(1);
+    expect(executor).toHaveBeenCalledTimes(1);
+    if (result.status === 'success') {
+      expect(result.result).toBe('result');
+    }
+  });
+
+  it('retries and succeeds on second attempt', async () => {
+    const validator = vi.fn()
+      .mockReturnValueOnce({ valid: false, errors: ['fail 1'], warnings: [] })
+      .mockReturnValueOnce({ valid: true, errors: [], warnings: [] });
+
+    const result = await ralph({
+      executor: async () => 'result',
+      validator,
+      maxAttempts: 3,
+      retryStrategy: noDelay()
+    });
+
+    expect(result.status).toBe('success');
+    expect(result.attempts).toBe(2);
+    expect(validator).toHaveBeenCalledTimes(2);
+  });
+
+  it('returns exhausted after max attempts', async () => {
+    const validator = vi.fn().mockReturnValue({
+      valid: false,
+      errors: ['always fails'],
+      warnings: []
+    });
+
+    const result = await ralph({
+      executor: async () => 'result',
+      validator,
+      maxAttempts: 3,
+      retryStrategy: noDelay()
+    });
+
+    expect(result.status).toBe('exhausted');
+    expect(result.attempts).toBe(3);
+    if (result.status === 'exhausted') {
+      expect(result.failures).toHaveLength(3);
+      expect(result.failures).toEqual(['always fails', 'always fails', 'always fails']);
+    }
+  });
+
+  it('passes execution context with previousFailures', async () => {
+    const executorCalls: ExecutionContext[] = [];
+
+    const executor = vi.fn(async (ctx: ExecutionContext) => {
+      executorCalls.push({ ...ctx });
+      return 'result';
+    });
+
+    const validator = vi.fn()
+      .mockReturnValueOnce({ valid: false, errors: ['error 1'], warnings: [] })
+      .mockReturnValueOnce({ valid: false, errors: ['error 2'], warnings: [] })
+      .mockReturnValueOnce({ valid: true, errors: [], warnings: [] });
+
+    await ralph({
+      executor,
+      validator,
+      maxAttempts: 5,
+      retryStrategy: noDelay()
+    });
+
+    // First call: no previous failures
+    expect(executorCalls[0]).toEqual({ attempt: 1, previousFailures: [] });
+
+    // Second call: has first error
+    expect(executorCalls[1]).toEqual({ attempt: 2, previousFailures: ['error 1'] });
+
+    // Third call: has both errors
+    expect(executorCalls[2]).toEqual({ attempt: 3, previousFailures: ['error 1', 'error 2'] });
+  });
+
+  it('calls onRetry callback on each retry', async () => {
+    const onRetry = vi.fn();
+    const validator = vi.fn()
+      .mockReturnValueOnce({ valid: false, errors: ['fail'], warnings: [] })
+      .mockReturnValueOnce({ valid: true, errors: [], warnings: [] });
+
+    await ralph({
+      executor: async () => 'result',
+      validator,
+      maxAttempts: 3,
+      retryStrategy: noDelay(),
+      onRetry
+    });
+
+    expect(onRetry).toHaveBeenCalledTimes(1);
+    expect(onRetry.mock.calls[0][0]).toMatchObject({
+      attempt: 1,
+      result: 'result',
+      validation: { valid: false, errors: ['fail'], warnings: [] },
+      allFailures: ['fail']
+    });
+  });
+
+  it('calls onSuccess on successful completion', async () => {
+    const onSuccess = vi.fn();
+
+    await ralph({
+      executor: async () => 'result',
+      validator: () => ({ valid: true, errors: [], warnings: [] }),
+      maxAttempts: 3,
+      retryStrategy: noDelay(),
+      onSuccess
+    });
+
+    expect(onSuccess).toHaveBeenCalledWith('result', 1);
+  });
+
+  it('calls onExhausted when max attempts reached', async () => {
+    const onExhausted = vi.fn();
+
+    await ralph({
+      executor: async () => 'result',
+      validator: () => ({ valid: false, errors: ['fail'], warnings: [] }),
+      maxAttempts: 2,
+      retryStrategy: noDelay(),
+      onExhausted
+    });
+
+    expect(onExhausted).toHaveBeenCalledWith('result', ['fail', 'fail']);
+  });
+
+  it('does not call onRetry on last failed attempt', async () => {
+    const onRetry = vi.fn();
+
+    await ralph({
+      executor: async () => 'result',
+      validator: () => ({ valid: false, errors: ['fail'], warnings: [] }),
+      maxAttempts: 2,
+      retryStrategy: noDelay(),
+      onRetry
+    });
+
+    // Should only retry once (between attempt 1 and 2)
+    expect(onRetry).toHaveBeenCalledTimes(1);
+  });
+
+  it('accumulates errors from multiple validation failures', async () => {
+    const validator = vi.fn()
+      .mockReturnValueOnce({ valid: false, errors: ['error A', 'error B'], warnings: [] })
+      .mockReturnValueOnce({ valid: false, errors: ['error C'], warnings: [] });
+
+    const result = await ralph({
+      executor: async () => 'result',
+      validator,
+      maxAttempts: 2,
+      retryStrategy: noDelay()
+    });
+
+    if (result.status === 'exhausted') {
+      expect(result.failures).toEqual(['error A', 'error B', 'error C']);
+    }
+  });
+
+  it('supports async validators', async () => {
+    const validator = vi.fn(async () => {
+      await new Promise(resolve => setTimeout(resolve, 1));
+      return { valid: true, errors: [], warnings: [] };
+    });
+
+    const result = await ralph({
+      executor: async () => 'result',
+      validator,
+      maxAttempts: 3,
+      retryStrategy: noDelay()
+    });
+
+    expect(result.status).toBe('success');
+  });
+
+  it('supports async callbacks', async () => {
+    const onRetry = vi.fn(async () => {
+      await new Promise(resolve => setTimeout(resolve, 1));
+    });
+
+    const validator = vi.fn()
+      .mockReturnValueOnce({ valid: false, errors: ['fail'], warnings: [] })
+      .mockReturnValueOnce({ valid: true, errors: [], warnings: [] });
+
+    await ralph({
+      executor: async () => 'result',
+      validator,
+      maxAttempts: 3,
+      retryStrategy: noDelay(),
+      onRetry
+    });
+
+    expect(onRetry).toHaveBeenCalled();
+  });
+
+  it('returns cancelled immediately when signal is already aborted', async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const executor = vi.fn().mockResolvedValue('result');
+    const validator = vi.fn().mockReturnValue({ valid: true, errors: [], warnings: [] });
+
+    const result = await ralph({
+      executor,
+      validator,
+      maxAttempts: 3,
+      retryStrategy: noDelay(),
+      signal: controller.signal,
+    });
+
+    expect(result.status).toBe('cancelled');
+    expect(executor).not.toHaveBeenCalled();
+  });
+
+  it('returns cancelled when signal aborts between attempts', async () => {
+    const controller = new AbortController();
+
+    const executor = vi.fn().mockResolvedValue('result');
+    const validator = vi.fn().mockReturnValueOnce({ valid: false, errors: ['fail'], warnings: [] });
+
+    // Abort after first validation
+    validator.mockImplementationOnce(() => {
+      controller.abort();
+      return { valid: false, errors: ['fail 2'], warnings: [] };
+    });
+
+    const result = await ralph({
+      executor,
+      validator,
+      maxAttempts: 5,
+      retryStrategy: noDelay(),
+      signal: controller.signal,
+    });
+
+    expect(result.status).toBe('cancelled');
+    expect(executor).toHaveBeenCalledTimes(2);
+  });
+
+  it('returns cancelled when executor throws AbortError', async () => {
+    const controller = new AbortController();
+
+    const executor = vi.fn().mockImplementation(async () => {
+      controller.abort();
+      const err = new DOMException('The operation was aborted', 'AbortError');
+      throw err;
+    });
+    const validator = vi.fn();
+
+    const result = await ralph({
+      executor,
+      validator,
+      maxAttempts: 3,
+      retryStrategy: noDelay(),
+      signal: controller.signal,
+    });
+
+    expect(result.status).toBe('cancelled');
+    expect(validator).not.toHaveBeenCalled();
+  });
+
+  it('cancellation resolves pending retry delay immediately', async () => {
+    const controller = new AbortController();
+
+    let attempt = 0;
+    const executor = vi.fn().mockImplementation(async () => {
+      attempt++;
+      if (attempt === 1) {
+        // After first attempt, schedule abort in 5ms (well before any real delay)
+        setTimeout(() => controller.abort(), 5);
+      }
+      return 'result';
+    });
+    const validator = vi.fn().mockReturnValue({ valid: false, errors: ['fail'], warnings: [] });
+
+    const start = Date.now();
+    const result = await ralph({
+      executor,
+      validator,
+      maxAttempts: 5,
+      retryStrategy: { getDelay: () => 60_000 }, // 60 second delay — should NOT wait
+      signal: controller.signal,
+    });
+
+    const elapsed = Date.now() - start;
+    expect(result.status).toBe('cancelled');
+    expect(elapsed).toBeLessThan(5000); // Way less than 60s
+  });
+
+  it('works with object result type (generic T)', async () => {
+    type Output = { value: number; label: string };
+
+    const result = await ralph<Output>({
+      executor: async () => ({ value: 42, label: 'ok' }),
+      validator: () => ({ valid: true, errors: [], warnings: [] }),
+      maxAttempts: 3,
+      retryStrategy: noDelay()
+    });
+
+    expect(result.status).toBe('success');
+    if (result.status === 'success') {
+      expect(result.result.value).toBe(42);
+      expect(result.result.label).toBe('ok');
+    }
+  });
+
+  it('exhausts immediately with maxAttempts=1 on first failure', async () => {
+    const validator = vi.fn().mockReturnValue({
+      valid: false,
+      errors: ['always fails'],
+      warnings: []
+    });
+
+    const result = await ralph({
+      executor: async () => 'result',
+      validator,
+      maxAttempts: 1,
+      retryStrategy: noDelay()
+    });
+
+    expect(result.status).toBe('exhausted');
+    expect(result.attempts).toBe(1);
+    if (result.status === 'exhausted') {
+      expect(result.failures).toEqual(['always fails']);
+    }
+    expect(validator).toHaveBeenCalledTimes(1);
+  });
+
+  it('propagates executor exceptions that are not abort errors', async () => {
+    const error = new Error('unexpected failure');
+
+    await expect(ralph({
+      executor: async () => { throw error; },
+      validator: () => ({ valid: true, errors: [], warnings: [] }),
+      maxAttempts: 3,
+      retryStrategy: noDelay()
+    })).rejects.toThrow('unexpected failure');
+  });
+});

package/tests/retry.test.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect } from 'vitest';
+import { noDelay, fixedDelay, exponentialBackoff } from '../src/retry-strategy.js';
+
+describe('noDelay', () => {
+  it('always returns 0', () => {
+    const strategy = noDelay();
+    expect(strategy.getDelay(1)).toBe(0);
+    expect(strategy.getDelay(2)).toBe(0);
+    expect(strategy.getDelay(100)).toBe(0);
+  });
+
+  it('returns 0 for all attempts', () => {
+    const strategy = noDelay();
+    for (let i = 1; i <= 10; i++) {
+      expect(strategy.getDelay(i)).toBe(0);
+    }
+  });
+});
+
+describe('fixedDelay', () => {
+  it('always returns same delay', () => {
+    const strategy = fixedDelay(1000);
+    expect(strategy.getDelay(1)).toBe(1000);
+    expect(strategy.getDelay(2)).toBe(1000);
+    expect(strategy.getDelay(5)).toBe(1000);
+    expect(strategy.getDelay(100)).toBe(1000);
+  });
+
+  it('works with different delay values', () => {
+    expect(fixedDelay(500).getDelay(1)).toBe(500);
+    expect(fixedDelay(2000).getDelay(1)).toBe(2000);
+    expect(fixedDelay(100).getDelay(1)).toBe(100);
+  });
+
+  it('works with zero delay', () => {
+    const strategy = fixedDelay(0);
+    expect(strategy.getDelay(1)).toBe(0);
+  });
+});
+
+describe('exponentialBackoff', () => {
+  it('doubles each attempt', () => {
+    const strategy = exponentialBackoff(1000, 10000);
+    expect(strategy.getDelay(1)).toBe(1000);  // 1000 * 2^0
+    expect(strategy.getDelay(2)).toBe(2000);  // 1000 * 2^1
+    expect(strategy.getDelay(3)).toBe(4000);  // 1000 * 2^2
+    expect(strategy.getDelay(4)).toBe(8000);  // 1000 * 2^3
+  });
+
+  it('caps at maxMs', () => {
+    const strategy = exponentialBackoff(1000, 5000);
+    expect(strategy.getDelay(1)).toBe(1000);
+    expect(strategy.getDelay(2)).toBe(2000);
+    expect(strategy.getDelay(3)).toBe(4000);
+    expect(strategy.getDelay(4)).toBe(5000); // Would be 8000 but capped
+    expect(strategy.getDelay(5)).toBe(5000); // Would be 16000 but capped
+    expect(strategy.getDelay(10)).toBe(5000); // Would be 512000 but capped
+  });
+
+  it('works with different base values', () => {
+    const strategy = exponentialBackoff(100, 10000);
+    expect(strategy.getDelay(1)).toBe(100);
+    expect(strategy.getDelay(2)).toBe(200);
+    expect(strategy.getDelay(3)).toBe(400);
+    expect(strategy.getDelay(4)).toBe(800);
+  });
+
+  it('respects max from the start if base > max', () => {
+    const strategy = exponentialBackoff(10000, 5000);
+    expect(strategy.getDelay(1)).toBe(5000); // 10000 capped to 5000
+  });
+
+  it('handles large attempt numbers without overflow', () => {
+    const strategy = exponentialBackoff(1000, 60000);
+    const delay = strategy.getDelay(100);
+    expect(delay).toBe(60000); // Should be capped, not Infinity
+    expect(delay).toBeLessThanOrEqual(60000);
+  });
+
+  it('works with small max values', () => {
+    const strategy = exponentialBackoff(10, 50);
+    expect(strategy.getDelay(1)).toBe(10);
+    expect(strategy.getDelay(2)).toBe(20);
+    expect(strategy.getDelay(3)).toBe(40);
+    expect(strategy.getDelay(4)).toBe(50); // Capped
+  });
+});