@ontrails/core 1.0.0-beta.0

package/src/__tests__/event.test.ts

@@ -0,0 +1,82 @@
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { event } from '../event';
+
+const payloadSchema = z.object({
+  action: z.string(),
+  userId: z.string(),
+});
+
+const userAction = event('user.action', {
+  description: 'A user performed an action',
+  from: ['auth.login', 'auth.signup'],
+  markers: { domain: 'auth', priority: 1 },
+  payload: payloadSchema,
+});
+
+describe('event() basics', () => {
+  test("returns kind 'event'", () => {
+    expect(userAction.kind).toBe('event');
+  });
+
+  test('returns correct id', () => {
+    expect(userAction.id).toBe('user.action');
+  });
+
+  test('preserves payload schema', () => {
+    const parsed = userAction.payload.safeParse({
+      action: 'click',
+      userId: 'u-1',
+    });
+    expect(parsed.success).toBe(true);
+
+    const bad = userAction.payload.safeParse({ userId: 42 });
+    expect(bad.success).toBe(false);
+  });
+
+  test('preserves description', () => {
+    expect(userAction.description).toBe('A user performed an action');
+  });
+
+  test('result object is frozen', () => {
+    expect(Object.isFrozen(userAction)).toBe(true);
+  });
+});
+
+describe('event() from and markers', () => {
+  test('preserves from', () => {
+    expect(userAction.from).toEqual(['auth.login', 'auth.signup']);
+  });
+
+  test('from array is frozen', () => {
+    expect(Object.isFrozen(userAction.from)).toBe(true);
+  });
+
+  test('preserves markers', () => {
+    expect(userAction.markers).toEqual({ domain: 'auth', priority: 1 });
+  });
+
+  test('optional fields default to undefined', () => {
+    const minimal = event('minimal', {
+      payload: z.string(),
+    });
+    expect(minimal.description).toBeUndefined();
+    expect(minimal.from).toBeUndefined();
+    expect(minimal.markers).toBeUndefined();
+  });
+});
+
+describe('event() single-object overload', () => {
+  test('accepts spec with id property', () => {
+    const e = event({
+      from: ['entity.add', 'entity.delete'],
+      id: 'entity.updated',
+      payload: z.object({ entityId: z.string() }),
+    });
+    expect(e.id).toBe('entity.updated');
+    expect(e.kind).toBe('event');
+    expect(e.from).toEqual(['entity.add', 'entity.delete']);
+  });
+});

package/src/__tests__/fetch.test.ts

@@ -0,0 +1,217 @@
+/* oxlint-disable require-await -- test mocks satisfy async interface without awaiting */
+import { describe, test, expect, afterEach } from 'bun:test';
+
+import {
+  AuthError,
+  CancelledError,
+  InternalError,
+  NetworkError,
+  NotFoundError,
+  PermissionError,
+  ValidationError,
+  RateLimitError,
+  TimeoutError,
+} from '../errors.js';
+import { Result } from '../result.js';
+
+// ---------------------------------------------------------------------------
+// Mock fetch
+// ---------------------------------------------------------------------------
+
+const originalFetch = globalThis.fetch;
+
+const mockFetch = (impl: () => Promise<Response>) => {
+  globalThis.fetch = impl as unknown as typeof globalThis.fetch;
+};
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+const fakeResponse = (
+  status: number,
+  options?: { headers?: Record<string, string> }
+): Response => {
+  const init: ResponseInit = { status };
+  if (options?.headers) {
+    init.headers = options.headers;
+  }
+  return new Response(null, init);
+};
+
+// ---------------------------------------------------------------------------
+// Successful responses
+// ---------------------------------------------------------------------------
+
+describe('Result.fromFetch — success', () => {
+  test('returns Ok with Response for 200', async () => {
+    mockFetch(async () => fakeResponse(200));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap().status).toBe(200);
+  });
+
+  test('returns Ok for 201', async () => {
+    mockFetch(async () => fakeResponse(201));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isOk()).toBe(true);
+  });
+
+  test('returns Ok for 204', async () => {
+    mockFetch(async () => fakeResponse(204));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isOk()).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// HTTP error status mapping
+// ---------------------------------------------------------------------------
+
+describe('Result.fromFetch — status code mapping', () => {
+  test('401 → AuthError', async () => {
+    mockFetch(async () => fakeResponse(401));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      AuthError
+    );
+  });
+
+  test('403 → PermissionError', async () => {
+    mockFetch(async () => fakeResponse(403));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      PermissionError
+    );
+  });
+
+  test('404 → NotFoundError', async () => {
+    mockFetch(async () => fakeResponse(404));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      NotFoundError
+    );
+  });
+
+  test('429 → RateLimitError', async () => {
+    mockFetch(async () => fakeResponse(429));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      RateLimitError
+    );
+  });
+
+  test('429 with retry-after header', async () => {
+    mockFetch(async () =>
+      fakeResponse(429, { headers: { 'retry-after': '30' } })
+    );
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    const err = (result as unknown as { error: RateLimitError }).error;
+    expect(err).toBeInstanceOf(RateLimitError);
+    expect(err.retryAfter).toBe(30);
+  });
+
+  test('500 → InternalError', async () => {
+    mockFetch(async () => fakeResponse(500));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      InternalError
+    );
+  });
+
+  test('502 → NetworkError', async () => {
+    mockFetch(async () => fakeResponse(502));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      NetworkError
+    );
+  });
+
+  test('504 → TimeoutError', async () => {
+    mockFetch(async () => fakeResponse(504));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      TimeoutError
+    );
+  });
+
+  test('503 → InternalError (generic 5xx)', async () => {
+    mockFetch(async () => fakeResponse(503));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      InternalError
+    );
+  });
+
+  test('400 → ValidationError', async () => {
+    mockFetch(async () => fakeResponse(400));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      ValidationError
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Network / abort errors
+// ---------------------------------------------------------------------------
+
+describe('Result.fromFetch — network errors', () => {
+  test('TypeError → NetworkError', async () => {
+    mockFetch(async () => {
+      throw new TypeError('Failed to fetch');
+    });
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      NetworkError
+    );
+  });
+
+  test('AbortError → CancelledError', async () => {
+    mockFetch(async () => {
+      throw new DOMException('The operation was aborted', 'AbortError');
+    });
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      CancelledError
+    );
+  });
+
+  test('unknown thrown value → NetworkError', async () => {
+    mockFetch(async () => {
+      // oxlint-disable-next-line no-throw-literal -- intentionally testing non-Error rejection handling
+      throw 'string error';
+    });
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    expect((result as unknown as { error: Error }).error).toBeInstanceOf(
+      NetworkError
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Error context
+// ---------------------------------------------------------------------------
+
+describe('Result.fromFetch — error context', () => {
+  test('includes status in error context', async () => {
+    mockFetch(async () => fakeResponse(404));
+    const result = await Result.fromFetch('https://example.com/api');
+    expect(result.isErr()).toBe(true);
+    const err = (result as unknown as { error: NotFoundError }).error;
+    expect(err.context?.['status']).toBe(404);
+  });
+});

package/src/__tests__/guards.test.ts

@@ -0,0 +1,102 @@
+import { describe, test, expect } from 'bun:test';
+
+import {
+  isDefined,
+  isNonEmptyString,
+  isPlainObject,
+  hasProperty,
+  assertNever,
+} from '../guards';
+
+describe('guards', () => {
+  describe('isDefined()', () => {
+    test('returns true for non-nullish values', () => {
+      expect(isDefined(0)).toBe(true);
+      expect(isDefined('')).toBe(true);
+      expect(isDefined(false)).toBe(true);
+      expect(isDefined([])).toBe(true);
+    });
+
+    test('returns false for null', () => {
+      expect(isDefined(null)).toBe(false);
+    });
+
+    test('returns false for undefined', () => {
+      expect(isDefined()).toBe(false);
+    });
+  });
+
+  describe('isNonEmptyString()', () => {
+    test('returns true for non-empty strings', () => {
+      expect(isNonEmptyString('hello')).toBe(true);
+      expect(isNonEmptyString(' ')).toBe(true);
+    });
+
+    test('returns false for empty string', () => {
+      expect(isNonEmptyString('')).toBe(false);
+    });
+
+    test('returns false for non-string types', () => {
+      expect(isNonEmptyString(42)).toBe(false);
+      expect(isNonEmptyString(null)).toBe(false);
+      expect(isNonEmptyString()).toBe(false);
+      expect(isNonEmptyString([])).toBe(false);
+    });
+  });
+
+  describe('isPlainObject()', () => {
+    test('returns true for plain objects', () => {
+      expect(isPlainObject({})).toBe(true);
+      expect(isPlainObject({ a: 1 })).toBe(true);
+      expect(isPlainObject(Object.create(null))).toBe(true);
+    });
+
+    test('returns false for arrays', () => {
+      expect(isPlainObject([])).toBe(false);
+    });
+
+    test('returns false for class instances', () => {
+      expect(isPlainObject(new Date())).toBe(false);
+      expect(isPlainObject(new Map())).toBe(false);
+    });
+
+    test('returns false for null', () => {
+      expect(isPlainObject(null)).toBe(false);
+    });
+
+    test('returns false for primitives', () => {
+      expect(isPlainObject('string')).toBe(false);
+      expect(isPlainObject(42)).toBe(false);
+    });
+  });
+
+  describe('hasProperty()', () => {
+    test('returns true when key exists', () => {
+      expect(hasProperty({ name: 'test' }, 'name')).toBe(true);
+    });
+
+    test('returns true for keys with undefined values', () => {
+      expect(hasProperty({ x: undefined }, 'x')).toBe(true);
+    });
+
+    test('returns false when key is missing', () => {
+      expect(hasProperty({}, 'missing')).toBe(false);
+    });
+
+    test('returns false for null', () => {
+      expect(hasProperty(null, 'key')).toBe(false);
+    });
+
+    test('returns false for primitives', () => {
+      expect(hasProperty(42, 'key')).toBe(false);
+    });
+  });
+
+  describe('assertNever()', () => {
+    test('throws with a descriptive message', () => {
+      expect(() => assertNever('unexpected' as never)).toThrow(
+        'Unexpected value: unexpected'
+      );
+    });
+  });
+});

package/src/__tests__/hike.test.ts

@@ -0,0 +1,117 @@
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { Result } from '../result';
+import { hike } from '../hike';
+import type { TrailContext } from '../types';
+
+const stubCtx: TrailContext = {
+  requestId: 'test-123',
+  signal: AbortSignal.timeout(5000),
+};
+
+describe('hike()', () => {
+  const inputSchema = z.object({ userId: z.string() });
+  const outputSchema = z.object({ profile: z.string() });
+
+  const fetchProfile = hike('fetch-profile', {
+    description: 'Fetch a user profile',
+    follows: ['authenticate', 'validate-session'],
+    implementation: (input) =>
+      Result.ok({ profile: `Profile for ${input.userId}` }),
+    input: inputSchema,
+    output: outputSchema,
+  });
+
+  describe('basics', () => {
+    test("returns kind 'hike'", () => {
+      expect(fetchProfile.kind).toBe('hike');
+    });
+
+    test('returns correct id', () => {
+      expect(fetchProfile.id).toBe('fetch-profile');
+    });
+
+    test('preserves follows array', () => {
+      expect(fetchProfile.follows).toEqual([
+        'authenticate',
+        'validate-session',
+      ]);
+    });
+
+    test('follows array is frozen', () => {
+      expect(Object.isFrozen(fetchProfile.follows)).toBe(true);
+    });
+  });
+
+  describe('trail compatibility', () => {
+    test('extends Trail — has input schema', () => {
+      const parsed = fetchProfile.input.safeParse({ userId: 'u-1' });
+      expect(parsed.success).toBe(true);
+    });
+
+    test('extends Trail — has output schema', () => {
+      expect(fetchProfile.output).toBeDefined();
+    });
+
+    test('extends Trail — implementation is callable', async () => {
+      const result = await fetchProfile.implementation(
+        { userId: 'u-1' },
+        stubCtx
+      );
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ profile: 'Profile for u-1' });
+    });
+
+    test('preserves description', () => {
+      expect(fetchProfile.description).toBe('Fetch a user profile');
+    });
+
+    test('result object is frozen', () => {
+      expect(Object.isFrozen(fetchProfile)).toBe(true);
+    });
+  });
+
+  test('markers are preserved', () => {
+    const withMarkers = hike('tagged-hike', {
+      follows: ['setup'],
+      implementation: () => Result.ok(),
+      input: z.object({}),
+      markers: { domain: 'auth' },
+    });
+    expect(withMarkers.markers).toEqual({ domain: 'auth' });
+  });
+
+  describe('single-object overload', () => {
+    test('accepts spec with id property', () => {
+      const r = hike({
+        follows: ['entity.add', 'entity.relate'],
+        id: 'entity.onboard',
+        implementation: () => Result.ok(),
+        input: z.object({}),
+      });
+      expect(r.id).toBe('entity.onboard');
+      expect(r.kind).toBe('hike');
+      expect(r.follows).toEqual(['entity.add', 'entity.relate']);
+    });
+
+    test('sync implementations are normalized to an awaitable runtime function', async () => {
+      const r = hike({
+        follows: ['entity.add'],
+        id: 'entity.check',
+        implementation: (input: { userId: string }) =>
+          Result.ok({ profile: input.userId }),
+        input: inputSchema,
+        output: outputSchema,
+      });
+
+      const promise = r.implementation({ userId: 'u-2' }, stubCtx);
+      expect(promise).toBeInstanceOf(Promise);
+
+      const result = await promise;
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ profile: 'u-2' });
+    });
+  });
+});

package/src/__tests__/job.test.ts

@@ -0,0 +1,98 @@
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { jobOutputSchema } from '../job';
+
+describe('jobOutputSchema', () => {
+  test('parses a valid completed job output', () => {
+    const input = {
+      completedAt: '2026-03-25T00:01:00Z',
+      current: 10,
+      jobId: 'job-123',
+      percentage: 100,
+      result: { rows: 42 },
+      startedAt: '2026-03-25T00:00:00Z',
+      status: 'completed',
+      total: 10,
+    };
+
+    const parsed = jobOutputSchema.parse(input);
+
+    expect(parsed.jobId).toBe('job-123');
+    expect(parsed.status).toBe('completed');
+    expect(parsed.current).toBe(10);
+    expect(parsed.total).toBe(10);
+  });
+
+  test('parses a minimal pending job output', () => {
+    const input = {
+      current: 0,
+      jobId: 'job-456',
+      status: 'pending',
+      total: 100,
+    };
+
+    const parsed = jobOutputSchema.parse(input);
+
+    expect(parsed.jobId).toBe('job-456');
+    expect(parsed.status).toBe('pending');
+    expect(parsed.result).toBeUndefined();
+    expect(parsed.error).toBeUndefined();
+  });
+
+  test('parses a failed job with error', () => {
+    const input = {
+      current: 3,
+      error: 'connection reset',
+      jobId: 'job-789',
+      status: 'failed',
+      total: 10,
+    };
+
+    const parsed = jobOutputSchema.parse(input);
+
+    expect(parsed.status).toBe('failed');
+    expect(parsed.error).toBe('connection reset');
+  });
+
+  test('rejects when jobId is missing', () => {
+    const input = {
+      current: 1,
+      status: 'running',
+      total: 5,
+    };
+
+    expect(() => jobOutputSchema.parse(input)).toThrow();
+  });
+
+  test('rejects an invalid status value', () => {
+    const input = {
+      current: 0,
+      jobId: 'job-bad',
+      status: 'unknown',
+      total: 0,
+    };
+
+    expect(() => jobOutputSchema.parse(input)).toThrow();
+  });
+
+  test('composes statusFields and progressFields correctly', () => {
+    const { shape } = jobOutputSchema;
+
+    // Status field from statusFields()
+    expect(shape.status).toBeInstanceOf(z.ZodEnum);
+
+    // Progress fields from progressFields()
+    expect(shape.current).toBeInstanceOf(z.ZodNumber);
+    expect(shape.total).toBeInstanceOf(z.ZodNumber);
+    expect(shape.percentage).toBeDefined();
+
+    // Job-specific fields
+    expect(shape.jobId).toBeInstanceOf(z.ZodString);
+    expect(shape.error).toBeDefined();
+    expect(shape.result).toBeDefined();
+    expect(shape.startedAt).toBeDefined();
+    expect(shape.completedAt).toBeDefined();
+  });
+});