@ontrails/core 1.0.0-beta.15 → 1.0.0-beta.17

package/src/__tests__/resilience.test.ts

@@ -1,246 +0,0 @@
-import { describe, test, expect } from 'bun:test';
-
-import {
-  NetworkError,
-  ValidationError,
-  TimeoutError,
-  CancelledError,
-  RateLimitError,
-} from '../errors.js';
-import {
-  retry,
-  withTimeout,
-  shouldRetry,
-  deriveBackoffDelay,
-} 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);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// deriveBackoffDelay
-// ---------------------------------------------------------------------------
-
-describe('deriveBackoffDelay', () => {
-  test('returns a number >= 0', () => {
-    for (let i = 0; i < 20; i += 1) {
-      const delay = deriveBackoffDelay(0);
-      expect(delay).toBeGreaterThanOrEqual(0);
-    }
-  });
-
-  test('respects maxDelay cap', () => {
-    for (let i = 0; i < 20; i += 1) {
-      const delay = deriveBackoffDelay(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 = deriveBackoffDelay(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 }, () =>
-      deriveBackoffDelay(0, { baseDelay: 100 })
-    );
-    const samples3 = Array.from({ length: 100 }, () =>
-      deriveBackoffDelay(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__/resource.test.ts

@@ -1,204 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { z } from 'zod';
-
-import {
-  Result,
-  createTrailContext,
-  findDuplicateResourceId,
-  isResource,
-  resource,
-} from '../index.js';
-import type {
-  Resource,
-  ResourceContext,
-  ResourceSpec,
-  TrailContext,
-} from '../index.js';
-
-const resourceCtx: ResourceContext = {
-  config: {},
-  cwd: '/tmp/trails',
-  env: { DATABASE_URL: 'file::memory:' },
-  workspaceRoot: '/tmp',
-};
-
-let disposedValue: number | undefined;
-
-const counterResourceSpec: ResourceSpec<number> = {
-  create: () => Result.ok(3),
-  description: 'Counter resource',
-  dispose: (value) => {
-    disposedValue = value;
-  },
-  health: (value) => Result.ok({ healthy: value > 0 }),
-  meta: { domain: 'data' },
-  mock: () => 1,
-};
-
-const resolvedResourceCtx = (id: string, instance: unknown): TrailContext =>
-  createTrailContext({
-    abortSignal: new AbortController().signal,
-    extensions: { [id]: instance },
-    requestId: `${id}-request`,
-  });
-
-describe('resource types', () => {
-  test('ResourceContext exposes the stable process-scoped fields', () => {
-    expect(resourceCtx.cwd).toBe('/tmp/trails');
-    expect(resourceCtx.env?.DATABASE_URL).toBe('file::memory:');
-    expect(resourceCtx.workspaceRoot).toBe('/tmp');
-  });
-
-  test('ResourceSpec stores description and meta', () => {
-    expect(counterResourceSpec.description).toBe('Counter resource');
-    expect(counterResourceSpec.meta).toEqual({ domain: 'data' });
-  });
-
-  test('ResourceSpec can reserve a config schema for future composition', () => {
-    const config = z.object({ url: z.string().url() });
-    const spec: ResourceSpec<number> = {
-      config,
-      create: () => Result.ok(1),
-    };
-
-    expect(spec.config).toBe(config);
-  });
-
-  test('ResourceSpec create and health callbacks are callable', async () => {
-    const result = await counterResourceSpec.create(resourceCtx);
-    expect(result.isOk()).toBe(true);
-    expect(result.unwrap()).toBe(3);
-
-    const health = await counterResourceSpec.health?.(result.unwrap());
-    expect(health?.isOk()).toBe(true);
-    expect(health?.unwrap()).toEqual({ healthy: true });
-  });
-
-  test('ResourceSpec mock and dispose callbacks are callable', async () => {
-    disposedValue = undefined;
-    const result = await counterResourceSpec.create(resourceCtx);
-    expect(result.isOk()).toBe(true);
-
-    const instance = result.unwrap();
-    expect(await counterResourceSpec.mock?.()).toBe(1);
-
-    await counterResourceSpec.dispose?.(instance);
-    expect(disposedValue).toBe(3);
-  });
-
-  test('ResourceSpec create can be async', async () => {
-    const spec: ResourceSpec<number> = {
-      create: async () => {
-        await Bun.sleep(0);
-        return Result.ok(7);
-      },
-    };
-
-    const result = await spec.create(resourceCtx);
-    expect(result.isOk()).toBe(true);
-    expect(result.unwrap()).toBe(7);
-  });
-
-  test('Resource carries identity alongside the shared spec fields', async () => {
-    const counterResource: Resource<number> = {
-      from(ctx) {
-        return ctx.resource(this);
-      },
-      id: 'counter.main',
-      kind: 'resource',
-      ...counterResourceSpec,
-    };
-
-    expect(counterResource.kind).toBe('resource');
-    expect(counterResource.id).toBe('counter.main');
-
-    const created = await counterResource.create(resourceCtx);
-    expect(created.isOk()).toBe(true);
-    expect(created.unwrap()).toBe(3);
-    expect(await counterResource.mock?.()).toBe(1);
-  });
-});
-
-describe('resource()', () => {
-  test('returns a frozen resource object with kind and id', () => {
-    const counter = resource('counter.main', counterResourceSpec);
-
-    expect(counter.kind).toBe('resource');
-    expect(counter.id).toBe('counter.main');
-    expect(Object.isFrozen(counter)).toBe(true);
-  });
-
-  test('rejects resource ids containing a scope separator', () => {
-    expect(() => resource('billing:primary', counterResourceSpec)).toThrow(
-      'Resource "billing:primary" is invalid because resource ids may not contain ":"'
-    );
-  });
-
-  test('infers the resource type through from(ctx)', () => {
-    const db = resource('db.main', {
-      create: () =>
-        Result.ok({
-          query(sql: string) {
-            return sql.length;
-          },
-        }),
-      description: 'Typed database resource',
-    });
-
-    const store = {
-      query(sql: string) {
-        return sql.length;
-      },
-    };
-    const ctx = resolvedResourceCtx('db.main', store);
-
-    const resolved = db.from(ctx);
-    expect(resolved.query('select 1')).toBe(8);
-  });
-
-  test('from(ctx) throws when the resource is missing', () => {
-    const counter = resource('counter.main', counterResourceSpec);
-    const ctx = createTrailContext({
-      abortSignal: new AbortController().signal,
-      requestId: 'missing-resource',
-    });
-
-    expect(() => counter.from(ctx)).toThrow(
-      'Resource "counter.main" not provisioned in context'
-    );
-  });
-
-  test('from(ctx) returns undefined when the resource key exists with an undefined value', () => {
-    const optional = resource<undefined>('optional.main', {
-      create: () => Result.ok<undefined>(),
-    });
-    const ctx = createTrailContext({
-      abortSignal: new AbortController().signal,
-      extensions: { [optional.id]: undefined },
-      requestId: 'undefined-resource',
-    });
-
-    expect(optional.from(ctx)).toBeUndefined();
-  });
-});
-
-describe('resource helpers', () => {
-  test('isResource identifies resource definitions', () => {
-    const counter = resource('counter.main', counterResourceSpec);
-
-    expect(isResource(counter)).toBe(true);
-    expect(isResource({ id: 'counter.main', kind: 'trail' })).toBe(false);
-    expect(isResource(null)).toBe(false);
-  });
-
-  test('findDuplicateResourceId returns the first repeated ID', () => {
-    const first = resource('counter.main', counterResourceSpec);
-    const duplicate = resource('counter.main', counterResourceSpec);
-    const other = resource('counter.secondary', counterResourceSpec);
-
-    expect(findDuplicateResourceId([first, other])).toBeUndefined();
-    expect(findDuplicateResourceId([first, other, duplicate])).toBe(
-      'counter.main'
-    );
-  });
-});

package/src/__tests__/result.test.ts

@@ -1,155 +0,0 @@
-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([]);
-    });
-  });
-});