@ontrails/core 1.0.0-beta.0

package/src/__tests__/redaction.test.ts

@@ -0,0 +1,244 @@
+import { describe, test, expect } from 'bun:test';
+
+import { DEFAULT_SENSITIVE_KEYS, createRedactor } from '../redaction/index.js';
+
+// ---------------------------------------------------------------------------
+// DEFAULT_PATTERNS
+// ---------------------------------------------------------------------------
+
+describe('DEFAULT_PATTERNS', () => {
+  test('matches credit card numbers', () => {
+    const input = 'card: 4111-1111-1111-1111 end';
+    const redactor = createRedactor();
+    expect(redactor.redact(input)).toBe('card: [REDACTED] end');
+  });
+
+  test('matches credit card numbers with spaces', () => {
+    const input = 'card: 4111 1111 1111 1111 end';
+    const redactor = createRedactor();
+    expect(redactor.redact(input)).toBe('card: [REDACTED] end');
+  });
+
+  test('matches SSNs', () => {
+    const input = 'ssn is 123-45-6789';
+    const redactor = createRedactor();
+    expect(redactor.redact(input)).toBe('ssn is [REDACTED]');
+  });
+
+  test('matches bearer tokens', () => {
+    const input = 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9';
+    const redactor = createRedactor();
+    expect(redactor.redact(input)).toBe('Authorization: [REDACTED]');
+  });
+
+  test('matches basic auth', () => {
+    const input = 'Authorization: Basic dXNlcjpwYXNz';
+    const redactor = createRedactor();
+    expect(redactor.redact(input)).toBe('Authorization: [REDACTED]');
+  });
+
+  test('matches API keys with sk- prefix', () => {
+    const input = 'key: sk-abc123def456ghi';
+    const redactor = createRedactor();
+    expect(redactor.redact(input)).toBe('key: [REDACTED]');
+  });
+
+  test('matches API keys with pk_ prefix', () => {
+    const input = 'key: pk_live_abc123def456';
+    const redactor = createRedactor();
+    expect(redactor.redact(input)).toBe('key: [REDACTED]');
+  });
+
+  test('matches API keys with sk_ prefix', () => {
+    const input = 'key: sk_test_abc123def456';
+    const redactor = createRedactor();
+    expect(redactor.redact(input)).toBe('key: [REDACTED]');
+  });
+
+  test('matches JWT tokens', () => {
+    const input =
+      'jwt: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.abc123def456';
+    const redactor = createRedactor();
+    expect(redactor.redact(input)).toBe('jwt: [REDACTED]');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// DEFAULT_SENSITIVE_KEYS
+// ---------------------------------------------------------------------------
+
+describe('DEFAULT_SENSITIVE_KEYS', () => {
+  test('includes expected keys', () => {
+    const expected = [
+      'password',
+      'secret',
+      'token',
+      'apiKey',
+      'api_key',
+      'authorization',
+      'cookie',
+      'ssn',
+      'creditCard',
+      'credit_card',
+    ];
+    for (const key of expected) {
+      expect(DEFAULT_SENSITIVE_KEYS).toContain(key);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createRedactor().redact()
+// ---------------------------------------------------------------------------
+
+describe('createRedactor().redact()', () => {
+  test('replaces all matching patterns in a string', () => {
+    const redactor = createRedactor();
+    const input = 'cc: 4111-1111-1111-1111 ssn: 123-45-6789';
+    const result = redactor.redact(input);
+    expect(result).toBe('cc: [REDACTED] ssn: [REDACTED]');
+  });
+
+  test('returns string unchanged when no patterns match', () => {
+    const redactor = createRedactor();
+    const input = 'just a normal string';
+    expect(redactor.redact(input)).toBe('just a normal string');
+  });
+
+  test('works correctly when called multiple times (regex lastIndex reset)', () => {
+    const redactor = createRedactor();
+    const input = 'key: sk-abc123def456ghi';
+    expect(redactor.redact(input)).toBe('key: [REDACTED]');
+    expect(redactor.redact(input)).toBe('key: [REDACTED]');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createRedactor().redactObject()
+// ---------------------------------------------------------------------------
+
+describe('createRedactor().redactObject()', () => {
+  test('redacts values for sensitive keys', () => {
+    const redactor = createRedactor();
+    const obj = { password: 's3cret', username: 'alice' };
+    const result = redactor.redactObject(obj);
+    expect(result.password).toBe('[REDACTED]');
+    expect(result.username).toBe('alice');
+  });
+
+  test('matches sensitive keys case-insensitively', () => {
+    const redactor = createRedactor();
+    const obj = { Authorization: 'Bearer xyz', PASSWORD: 's3cret' };
+    const result = redactor.redactObject(obj);
+    expect(result.PASSWORD).toBe('[REDACTED]');
+    expect(result.Authorization).toBe('[REDACTED]');
+  });
+
+  test('applies pattern matching to non-sensitive string values', () => {
+    const redactor = createRedactor();
+    const obj = { message: 'card 4111-1111-1111-1111 found' };
+    const result = redactor.redactObject(obj);
+    expect(result.message).toBe('card [REDACTED] found');
+  });
+
+  test('does not modify the original object', () => {
+    const redactor = createRedactor();
+    const obj = { password: 's3cret' };
+    redactor.redactObject(obj);
+    expect(obj.password).toBe('s3cret');
+  });
+
+  test('preserves non-string values', () => {
+    const redactor = createRedactor();
+    const obj = { count: 42, enabled: true, tags: null as unknown };
+    const result = redactor.redactObject(obj);
+    expect(result.count).toBe(42);
+    expect(result.enabled).toBe(true);
+    expect(result.tags).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Nested objects
+// ---------------------------------------------------------------------------
+
+describe('nested objects', () => {
+  test('redacts deeply nested sensitive keys', () => {
+    const redactor = createRedactor();
+    const obj = {
+      user: {
+        credentials: {
+          password: 's3cret',
+          token: 'tok_abc123',
+        },
+        name: 'alice',
+      },
+    };
+    const result = redactor.redactObject(obj);
+    expect(result.user.name).toBe('alice');
+    expect(result.user.credentials.password).toBe('[REDACTED]');
+    expect(result.user.credentials.token).toBe('[REDACTED]');
+  });
+
+  test('redacts values inside arrays', () => {
+    const redactor = createRedactor();
+    const obj = {
+      headers: [
+        { key: 'Authorization', value: 'Bearer abc123' },
+        { key: 'Content-Type', value: 'application/json' },
+      ],
+    };
+    const result = redactor.redactObject(obj);
+    expect(result.headers).toHaveLength(2);
+    expect(result.headers[0]?.value).toBe('[REDACTED]');
+    expect(result.headers[1]?.value).toBe('application/json');
+  });
+
+  test('handles deeply nested pattern matches', () => {
+    const redactor = createRedactor();
+    const obj = {
+      data: {
+        nested: {
+          info: 'ssn: 123-45-6789',
+        },
+      },
+    };
+    const result = redactor.redactObject(obj);
+    expect(result.data.nested.info).toBe('ssn: [REDACTED]');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Custom config
+// ---------------------------------------------------------------------------
+
+describe('custom config', () => {
+  test('custom patterns work', () => {
+    const redactor = createRedactor({
+      patterns: [/secret-\w+/g],
+    });
+    expect(redactor.redact('found secret-banana here')).toBe(
+      'found [REDACTED] here'
+    );
+    // Default patterns should not apply
+    expect(redactor.redact('4111-1111-1111-1111')).toBe('4111-1111-1111-1111');
+  });
+
+  test('custom replacement string works', () => {
+    const redactor = createRedactor({ replacement: '***' });
+    const obj = { password: 's3cret' };
+    const result = redactor.redactObject(obj);
+    expect(result.password).toBe('***');
+  });
+
+  test('custom sensitive keys work', () => {
+    const redactor = createRedactor({
+      sensitiveKeys: ['myCustomKey'],
+    });
+    const obj = { myCustomKey: 'hidden', password: 'visible' };
+    const result = redactor.redactObject(obj);
+    expect(result.myCustomKey).toBe('[REDACTED]');
+    // "password" is not in custom keys, so not redacted by key match
+    expect(result.password).toBe('visible');
+  });
+});

package/src/__tests__/resilience.test.ts

@@ -0,0 +1,246 @@
+import { describe, test, expect } from 'bun:test';
+
+import {
+  NetworkError,
+  ValidationError,
+  TimeoutError,
+  CancelledError,
+  RateLimitError,
+} from '../errors.js';
+import {
+  retry,
+  withTimeout,
+  shouldRetry,
+  getBackoffDelay,
+} from '../resilience.js';
+import { Result } from '../result.js';
+
+// ---------------------------------------------------------------------------
+// shouldRetry
+// ---------------------------------------------------------------------------
+
+describe('shouldRetry', () => {
+  test('returns true for retryable TrailsErrors', () => {
+    expect(shouldRetry(new NetworkError('down'))).toBe(true);
+    expect(shouldRetry(new TimeoutError('slow'))).toBe(true);
+    expect(shouldRetry(new RateLimitError('throttled'))).toBe(true);
+  });
+
+  test('returns false for non-retryable TrailsErrors', () => {
+    expect(shouldRetry(new ValidationError('bad'))).toBe(false);
+    expect(shouldRetry(new CancelledError('stop'))).toBe(false);
+  });
+
+  test('returns false for plain Error', () => {
+    expect(shouldRetry(new Error('generic'))).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getBackoffDelay
+// ---------------------------------------------------------------------------
+
+describe('getBackoffDelay', () => {
+  test('returns a number >= 0', () => {
+    for (let i = 0; i < 20; i += 1) {
+      const delay = getBackoffDelay(0);
+      expect(delay).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  test('respects maxDelay cap', () => {
+    for (let i = 0; i < 20; i += 1) {
+      const delay = getBackoffDelay(10, { maxDelay: 100 });
+      expect(delay).toBeLessThanOrEqual(100);
+    }
+  });
+
+  test('uses provided baseDelay and backoffFactor', () => {
+    // With attempt=0, exponential = base * factor^0 = base
+    // Jitter is [0, base], so delay <= base
+    for (let i = 0; i < 20; i += 1) {
+      const delay = getBackoffDelay(0, { backoffFactor: 3, baseDelay: 500 });
+      expect(delay).toBeLessThanOrEqual(500);
+    }
+  });
+
+  test('scales with attempt number', () => {
+    // Higher attempts should have higher caps (on average)
+    const samples0 = Array.from({ length: 100 }, () =>
+      getBackoffDelay(0, { baseDelay: 100 })
+    );
+    const samples3 = Array.from({ length: 100 }, () =>
+      getBackoffDelay(3, { baseDelay: 100 })
+    );
+    const avg0 = samples0.reduce((a, b) => a + b, 0) / samples0.length;
+    const avg3 = samples3.reduce((a, b) => a + b, 0) / samples3.length;
+    // Attempt 3 should have a noticeably higher average
+    expect(avg3).toBeGreaterThan(avg0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// retry
+// ---------------------------------------------------------------------------
+
+describe('retry', () => {
+  test('returns Ok on first success', async () => {
+    let calls = 0;
+    const result = await retry(() => {
+      calls += 1;
+      return Promise.resolve(Result.ok('done'));
+    });
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe('done');
+    expect(calls).toBe(1);
+  });
+
+  test('retries on retryable error', async () => {
+    const responses: Result<string, Error>[] = [
+      Result.err(new NetworkError('fail')),
+      Result.err(new NetworkError('fail')),
+      Result.ok('recovered'),
+    ];
+    let calls = 0;
+    const result = await retry(
+      () => {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- index is bounded by maxAttempts
+        const r = responses[calls]!;
+        calls += 1;
+        return Promise.resolve(r);
+      },
+      { baseDelay: 1, maxAttempts: 3 }
+    );
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe('recovered');
+    expect(calls).toBe(3);
+  });
+
+  test('does not retry non-retryable errors', async () => {
+    let calls = 0;
+    const result = await retry(
+      () => {
+        calls += 1;
+        return Promise.resolve(Result.err(new ValidationError('bad')));
+      },
+      { baseDelay: 1, maxAttempts: 3 }
+    );
+    expect(result.isErr()).toBe(true);
+    expect(calls).toBe(1);
+  });
+
+  test('gives up after maxAttempts', async () => {
+    let calls = 0;
+    const result = await retry(
+      () => {
+        calls += 1;
+        return Promise.resolve(Result.err(new NetworkError('fail')));
+      },
+      { baseDelay: 1, maxAttempts: 2 }
+    );
+    expect(result.isErr()).toBe(true);
+    expect(calls).toBe(2);
+  });
+
+  test('respects custom shouldRetry predicate', async () => {
+    let calls = 0;
+    const result = await retry(
+      () => {
+        calls += 1;
+        return Promise.resolve(Result.err(new ValidationError('bad')));
+      },
+      {
+        baseDelay: 1,
+        maxAttempts: 3,
+        // always retry
+        shouldRetry: () => true,
+      }
+    );
+    expect(result.isErr()).toBe(true);
+    expect(calls).toBe(3);
+  });
+
+  test('cancels on abort signal', async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const result = await retry(
+      () => Promise.resolve(Result.ok('should not run')),
+      {
+        signal: controller.signal,
+      }
+    );
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: Error };
+    expect(err.error).toBeInstanceOf(CancelledError);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// withTimeout
+// ---------------------------------------------------------------------------
+
+describe('withTimeout', () => {
+  test('returns result when function completes in time', async () => {
+    const result = await withTimeout(
+      () => Promise.resolve(Result.ok('fast')),
+      1000
+    );
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe('fast');
+  });
+
+  test('returns TimeoutError when function exceeds timeout', async () => {
+    const result = await withTimeout(
+      () =>
+        // oxlint-disable-next-line avoid-new -- Promise constructor needed for setTimeout-based delay
+        new Promise<Result<string, Error>>((resolve) => {
+          setTimeout(() => resolve(Result.ok('slow')), 500);
+        }),
+      10
+    );
+    expect(result.isErr()).toBe(true);
+    const err1 = result as unknown as { error: TimeoutError };
+    expect(err1.error).toBeInstanceOf(TimeoutError);
+    expect(err1.error.message).toContain('timed out');
+  });
+
+  test('returns CancelledError when signal is already aborted', async () => {
+    const controller = new AbortController();
+    controller.abort();
+
+    const result = await withTimeout(
+      () => Promise.resolve(Result.ok('value')),
+      1000,
+      controller.signal
+    );
+    expect(result.isErr()).toBe(true);
+    const err2 = result as unknown as { error: Error };
+    expect(err2.error).toBeInstanceOf(CancelledError);
+  });
+
+  test('handles function that throws', async () => {
+    const result = await withTimeout(
+      () => Promise.reject(new Error('unexpected')),
+      1000
+    );
+    expect(result.isErr()).toBe(true);
+    const err3 = result as unknown as { error: Error };
+    expect(err3.error.message).toBe('unexpected');
+  });
+
+  test('includes timeout ms in error context', async () => {
+    const result = await withTimeout(
+      () =>
+        // oxlint-disable-next-line avoid-new -- Promise constructor needed for setTimeout-based delay
+        new Promise<Result<string, Error>>((resolve) => {
+          setTimeout(() => resolve(Result.ok('slow')), 500);
+        }),
+      5
+    );
+    expect(result.isErr()).toBe(true);
+    const err4 = result as unknown as { error: TimeoutError };
+    expect(err4.error).toBeInstanceOf(TimeoutError);
+    expect(err4.error.context?.['timeoutMs']).toBe(5);
+  });
+});

package/src/__tests__/result.test.ts

@@ -0,0 +1,155 @@
+import { describe, test, expect } from 'bun:test';
+
+import { Result } from '../result';
+
+describe('Result', () => {
+  describe('construction', () => {
+    test('Result.ok() creates a success result', () => {
+      const result = Result.ok(42);
+      expect(result.isOk()).toBe(true);
+      expect(result.isErr()).toBe(false);
+    });
+
+    test('Result.err() creates a failure result', () => {
+      const result = Result.err(new Error('fail'));
+      expect(result.isOk()).toBe(false);
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  describe('type narrowing', () => {
+    test('isOk() narrows to Ok with value access', () => {
+      const result: Result<number, Error> = Result.ok(42);
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toBe(42);
+    });
+
+    test('isErr() narrows to Err with error access', () => {
+      const error = new Error('boom');
+      const result: Result<number, Error> = Result.err(error);
+      expect(result.isErr()).toBe(true);
+      expect((result as { error: Error }).error).toBe(error);
+    });
+  });
+
+  describe('map()', () => {
+    test('transforms the value of an Ok', () => {
+      const result = Result.ok(10).map((n) => n * 2);
+      expect(result.unwrap()).toBe(20);
+    });
+
+    test('passes through on Err', () => {
+      const error = new Error('fail');
+      const result = Result.err<Error>(error).map((_n: number) => 999);
+      expect(result.isErr()).toBe(true);
+      expect((result as { error: Error }).error).toBe(error);
+    });
+  });
+
+  describe('flatMap()', () => {
+    test('chains successful results', () => {
+      const result = Result.ok(10).flatMap((n) => Result.ok(n + 5));
+      expect(result.unwrap()).toBe(15);
+    });
+
+    test('short-circuits on error', () => {
+      const error = new Error('first');
+      const result = Result.err<Error>(error).flatMap((_n: number) =>
+        Result.ok(999)
+      );
+      expect(result.isErr()).toBe(true);
+      expect((result as { error: Error }).error).toBe(error);
+    });
+
+    test('chains into an error', () => {
+      const result = Result.ok(10).flatMap(() =>
+        Result.err(new Error('second'))
+      );
+      expect(result.isErr()).toBe(true);
+    });
+  });
+
+  describe('mapErr()', () => {
+    test('transforms the error of an Err', () => {
+      const result = Result.err('bad').mapErr((e) => new Error(e));
+      expect(result.isErr()).toBe(true);
+      expect((result as { error: Error }).error).toBeInstanceOf(Error);
+      expect((result as { error: Error }).error.message).toBe('bad');
+    });
+
+    test('passes through on Ok', () => {
+      const result = Result.ok(42).mapErr(() => 'transformed');
+      expect(result.unwrap()).toBe(42);
+    });
+  });
+
+  describe('match()', () => {
+    test('dispatches to ok handler on success', () => {
+      const output = Result.ok(5).match({
+        err: (e) => `error:${e}`,
+        ok: (v) => `value:${v}`,
+      });
+      expect(output).toBe('value:5');
+    });
+
+    test('dispatches to err handler on failure', () => {
+      const output = Result.err('oops').match({
+        err: (e) => `error:${e}`,
+        ok: (v) => `value:${v}`,
+      });
+      expect(output).toBe('error:oops');
+    });
+  });
+
+  describe('unwrap()', () => {
+    test('returns value on Ok', () => {
+      expect(Result.ok('hello').unwrap()).toBe('hello');
+    });
+
+    test('throws on Err with Error instance', () => {
+      const error = new Error('boom');
+      expect(() => Result.err(error).unwrap()).toThrow('boom');
+    });
+
+    test('throws wrapped error on Err with non-Error value', () => {
+      expect(() => Result.err('string error').unwrap()).toThrow('string error');
+    });
+  });
+
+  describe('unwrapOr()', () => {
+    test('returns value on Ok', () => {
+      expect(Result.ok(42).unwrapOr(0)).toBe(42);
+    });
+
+    test('returns fallback on Err', () => {
+      const result: Result<number, Error> = Result.err(new Error('fail'));
+      expect(result.unwrapOr(0)).toBe(0);
+    });
+  });
+
+  describe('Result.combine()', () => {
+    test('collects all Ok values into an array', () => {
+      const results = [Result.ok(1), Result.ok(2), Result.ok(3)];
+      const combined = Result.combine(results);
+      expect(combined.unwrap()).toEqual([1, 2, 3]);
+    });
+
+    test('returns first error encountered', () => {
+      const err1 = new Error('first');
+      const err2 = new Error('second');
+      const results: Result<number, Error>[] = [
+        Result.ok(1),
+        Result.err(err1),
+        Result.err(err2),
+      ];
+      const combined = Result.combine(results);
+      expect(combined.isErr()).toBe(true);
+      expect((combined as { error: Error }).error).toBe(err1);
+    });
+
+    test('returns Ok with empty array for empty input', () => {
+      const combined = Result.combine([]);
+      expect(combined.unwrap()).toEqual([]);
+    });
+  });
+});