@ontrails/core 1.0.0-beta.0

package/src/__tests__/serialization.test.ts

@@ -0,0 +1,236 @@
+import { describe, test, expect } from 'bun:test';
+
+import {
+  ValidationError,
+  NetworkError,
+  RateLimitError,
+  InternalError,
+  TimeoutError,
+  NotFoundError,
+} from '../errors.js';
+import { serializeError, deserializeError } from '../serialization.js';
+import { Result } from '../result.js';
+import type { SerializedError } from '../serialization.js';
+
+// ---------------------------------------------------------------------------
+// serializeError
+// ---------------------------------------------------------------------------
+
+describe('serializeError', () => {
+  test('serializes a plain Error', () => {
+    const err = new Error('boom');
+    const serialized = serializeError(err);
+    expect(serialized.name).toBe('Error');
+    expect(serialized.message).toBe('boom');
+    expect(serialized.stack).toBeDefined();
+    expect(serialized.category).toBeUndefined();
+    expect(serialized.retryable).toBeUndefined();
+  });
+
+  test('serializes a TrailsError with category', () => {
+    const err = new NetworkError('disconnected');
+    const serialized = serializeError(err);
+    expect(serialized.name).toBe('NetworkError');
+    expect(serialized.message).toBe('disconnected');
+    expect(serialized.category).toBe('network');
+    expect(serialized.retryable).toBe(true);
+  });
+
+  test('serializes context', () => {
+    const err = new ValidationError('bad input', {
+      context: { field: 'email' },
+    });
+    const serialized = serializeError(err);
+    expect(serialized.context).toEqual({ field: 'email' });
+  });
+
+  test('serializes RateLimitError.retryAfter', () => {
+    const err = new RateLimitError('slow down', { retryAfter: 30 });
+    const serialized = serializeError(err);
+    expect(serialized.retryAfter).toBe(30);
+  });
+
+  test('retryAfter is undefined for non-RateLimitError', () => {
+    const err = new TimeoutError('timed out');
+    const serialized = serializeError(err);
+    expect(serialized.retryAfter).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// deserializeError
+// ---------------------------------------------------------------------------
+
+describe('deserializeError', () => {
+  test('reconstructs a validation error', () => {
+    const data: SerializedError = {
+      category: 'validation',
+      message: 'bad input',
+      name: 'ValidationError',
+      retryable: false,
+    };
+    const err = deserializeError(data);
+    expect(err).toBeInstanceOf(ValidationError);
+    expect(err.message).toBe('bad input');
+    expect(err.category).toBe('validation');
+  });
+
+  test('reconstructs a rate limit error with retryAfter', () => {
+    const data: SerializedError = {
+      category: 'rate_limit',
+      message: 'slow down',
+      name: 'RateLimitError',
+      retryAfter: 60,
+      retryable: true,
+    };
+    const err = deserializeError(data);
+    expect(err).toBeInstanceOf(RateLimitError);
+    expect((err as RateLimitError).retryAfter).toBe(60);
+  });
+
+  test('restores stack trace', () => {
+    const data: SerializedError = {
+      category: 'internal',
+      message: 'oops',
+      name: 'InternalError',
+      stack: 'Error: oops\n    at test.ts:1:1',
+    };
+    const err = deserializeError(data);
+    expect(err.stack).toBe('Error: oops\n    at test.ts:1:1');
+  });
+
+  test('restores context', () => {
+    const data: SerializedError = {
+      category: 'auth',
+      context: { endpoint: '/api/secret' },
+      message: 'unauthorized',
+      name: 'AuthError',
+    };
+    const err = deserializeError(data);
+    expect(err.context).toEqual({ endpoint: '/api/secret' });
+  });
+
+  test('defaults to InternalError when category is missing', () => {
+    const data: SerializedError = {
+      message: 'unknown',
+      name: 'SomeError',
+    };
+    const err = deserializeError(data);
+    expect(err).toBeInstanceOf(InternalError);
+    expect(err.category).toBe('internal');
+  });
+
+  test('round-trips through serialize/deserialize', () => {
+    const original = new NotFoundError('missing resource', {
+      context: { id: 'abc' },
+    });
+    const serialized = serializeError(original);
+    const restored = deserializeError(serialized);
+    expect(restored).toBeInstanceOf(NotFoundError);
+    expect(restored.message).toBe('missing resource');
+    expect(restored.context).toEqual({ id: 'abc' });
+    expect(restored.category).toBe('not_found');
+  });
+
+  test('handles all error categories', () => {
+    const categories = [
+      'validation',
+      'not_found',
+      'conflict',
+      'permission',
+      'timeout',
+      'rate_limit',
+      'network',
+      'internal',
+      'auth',
+      'cancelled',
+    ] as const;
+
+    for (const category of categories) {
+      const data: SerializedError = {
+        category,
+        message: 'test',
+        name: 'Test',
+      };
+      const err = deserializeError(data);
+      expect(err.category).toBe(category);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Result.fromJson
+// ---------------------------------------------------------------------------
+
+describe('Result.fromJson (safeParse)', () => {
+  test('parses valid JSON', () => {
+    const result = Result.fromJson('{"key": "value"}');
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ key: 'value' });
+  });
+
+  test('parses JSON arrays', () => {
+    const result = Result.fromJson('[1, 2, 3]');
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual([1, 2, 3]);
+  });
+
+  test('parses JSON primitives', () => {
+    expect(Result.fromJson('"hello"').unwrap()).toBe('hello');
+    expect(Result.fromJson('42').unwrap()).toBe(42);
+    expect(Result.fromJson('true').unwrap()).toBe(true);
+    expect(Result.fromJson('null').unwrap()).toBe(null);
+  });
+
+  test('returns ValidationError for invalid JSON', () => {
+    const result = Result.fromJson('not json');
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: ValidationError };
+    expect(err.error).toBeInstanceOf(ValidationError);
+    expect(err.error.message).toBe('Invalid JSON');
+  });
+
+  test('includes truncated input in context', () => {
+    const result = Result.fromJson('{bad}');
+    expect(result.isErr()).toBe(true);
+    const err = result as unknown as { error: ValidationError };
+    expect(err.error.context).toBeDefined();
+    expect(err.error.context?.['input']).toBe('{bad}');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Result.toJson
+// ---------------------------------------------------------------------------
+
+describe('Result.toJson (safeStringify)', () => {
+  test('stringifies objects', () => {
+    const result = Result.toJson({ key: 'value' });
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe('{"key":"value"}');
+  });
+
+  test('stringifies arrays', () => {
+    const result = Result.toJson([1, 2, 3]);
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toBe('[1,2,3]');
+  });
+
+  test('stringifies primitives', () => {
+    expect(Result.toJson('hello').unwrap()).toBe('"hello"');
+    expect(Result.toJson(42).unwrap()).toBe('42');
+    expect(Result.toJson(true).unwrap()).toBe('true');
+    expect(Result.toJson(null).unwrap()).toBe('null');
+  });
+
+  test('handles circular references gracefully', () => {
+    const obj: Record<string, unknown> = { a: 1 };
+    obj['self'] = obj;
+    const result = Result.toJson(obj);
+    expect(result.isOk()).toBe(true);
+    const ok = result as unknown as { value: string };
+    const parsed = JSON.parse(ok.value) as Record<string, unknown>;
+    expect(parsed['a']).toBe(1);
+    expect(parsed['self']).toBe('[Circular]');
+  });
+});

package/src/__tests__/topo.test.ts

@@ -0,0 +1,184 @@
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { ValidationError } from '../errors.js';
+import { Result } from '../result.js';
+import { topo } from '../topo.js';
+
+// ---------------------------------------------------------------------------
+// Mock factories
+// ---------------------------------------------------------------------------
+
+// oxlint-disable-next-line require-await -- satisfies async interface without needing await
+const noop = async () => Result.ok();
+
+const mockTrail = (id: string) => ({
+  id,
+  implementation: noop,
+  input: z.object({ x: z.number() }),
+  kind: 'trail' as const,
+  output: z.object({ y: z.number() }),
+});
+
+const mockHike = (id: string) => ({
+  follows: [] as readonly string[],
+  id,
+  implementation: noop,
+  input: z.object({ q: z.string() }),
+  kind: 'hike' as const,
+  output: z.object({ r: z.string() }),
+  path: `/${id}`,
+});
+
+const mockEvent = (id: string) => ({
+  id,
+  kind: 'event' as const,
+  payload: z.object({ payload: z.string() }),
+});
+
+// ---------------------------------------------------------------------------
+// topo()
+// ---------------------------------------------------------------------------
+
+describe('topo', () => {
+  test('returns Topo with name', () => {
+    const t = topo('my-app');
+    expect(t.name).toBe('my-app');
+  });
+
+  test('collects trails from modules', () => {
+    const mod = { myTrail: mockTrail('create-user') };
+    const t = topo('app', mod);
+
+    expect(t.trails.size).toBe(1);
+    expect(t.trails.get('create-user')).toBe(mod.myTrail);
+  });
+
+  test('auto-scans exports by kind discriminant', () => {
+    const mod = {
+      event1: mockEvent('e1'),
+      hike1: mockHike('r1'),
+      trail1: mockTrail('t1'),
+    };
+    const t = topo('app', mod);
+
+    expect(t.trails.size).toBe(1);
+    expect(t.hikes.size).toBe(1);
+    expect(t.events.size).toBe(1);
+  });
+
+  test('collects from multiple modules', () => {
+    const mod1 = { a: mockTrail('t1') };
+    const mod2 = { b: mockTrail('t2'), c: mockHike('r1') };
+    const t = topo('app', mod1, mod2);
+
+    expect(t.trails.size).toBe(2);
+    expect(t.hikes.size).toBe(1);
+  });
+
+  test('non-trail exports are silently ignored', () => {
+    const mod = {
+      config: { port: 3000 },
+      helper: () => 'not a trail',
+      name: 'some-string',
+      nothing: null,
+      num: 42,
+      trail1: mockTrail('t1'),
+      undef: undefined,
+    };
+    const t = topo('app', mod);
+
+    expect(t.trails.size).toBe(1);
+    expect(t.hikes.size).toBe(0);
+    expect(t.events.size).toBe(0);
+  });
+
+  test('rejects duplicate trail IDs', () => {
+    const mod1 = { a: mockTrail('dup') };
+    const mod2 = { b: mockTrail('dup') };
+
+    expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
+    expect(() => topo('app', mod1, mod2)).toThrow('Duplicate trail ID: "dup"');
+  });
+
+  test('rejects duplicate hike IDs', () => {
+    const mod1 = { a: mockHike('dup') };
+    const mod2 = { b: mockHike('dup') };
+
+    expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
+    expect(() => topo('app', mod1, mod2)).toThrow('Duplicate hike ID: "dup"');
+  });
+
+  test('rejects duplicate event IDs', () => {
+    const mod1 = { a: mockEvent('dup') };
+    const mod2 = { b: mockEvent('dup') };
+
+    expect(() => topo('app', mod1, mod2)).toThrow(ValidationError);
+    expect(() => topo('app', mod1, mod2)).toThrow('Duplicate event ID: "dup"');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Topo
+// ---------------------------------------------------------------------------
+
+describe('Topo', () => {
+  const mod = {
+    e1: mockEvent('event-1'),
+    h1: mockHike('hike-1'),
+    t1: mockTrail('trail-1'),
+    t2: mockTrail('trail-2'),
+  };
+
+  // Build once for the describe block
+  const app = topo('app', mod);
+
+  describe('get()', () => {
+    test('retrieves trail by ID', () => {
+      expect(app.get('trail-1')).toBe(mod.t1);
+    });
+
+    test('retrieves hike by ID', () => {
+      expect(app.get('hike-1')).toBe(mod.h1);
+    });
+
+    test('returns undefined for unknown ID', () => {
+      expect(app.get('nope')).toBeUndefined();
+    });
+  });
+
+  describe('has()', () => {
+    test('returns true for known trail', () => {
+      expect(app.has('trail-1')).toBe(true);
+    });
+
+    test('returns true for known hike', () => {
+      expect(app.has('hike-1')).toBe(true);
+    });
+
+    test('returns false for unknown ID', () => {
+      expect(app.has('nope')).toBe(false);
+    });
+
+    test('returns false for event ID (events are not trails/hikes)', () => {
+      expect(app.has('event-1')).toBe(false);
+    });
+  });
+
+  describe('listing', () => {
+    test('list() returns all trails and hikes', () => {
+      const items = app.list();
+      expect(items).toHaveLength(3);
+      expect(items).toContain(mod.t1);
+      expect(items).toContain(mod.t2);
+      expect(items).toContain(mod.h1);
+    });
+
+    test('listEvents() returns all events', () => {
+      const items = app.listEvents();
+      expect(items).toHaveLength(1);
+      expect(items).toContain(mod.e1);
+    });
+  });
+});

package/src/__tests__/trail.test.ts

@@ -0,0 +1,179 @@
+import { describe, test, expect } from 'bun:test';
+
+import { z } from 'zod';
+
+import { Result } from '../result';
+import { trail } from '../trail';
+import type { TrailContext } from '../types';
+
+const stubCtx: TrailContext = {
+  requestId: 'test-123',
+  signal: AbortSignal.timeout(5000),
+};
+
+describe('trail()', () => {
+  const inputSchema = z.object({ name: z.string() });
+  const outputSchema = z.object({ greeting: z.string() });
+
+  const greet = trail('greet', {
+    description: 'Greet someone',
+    implementation: (input) => Result.ok({ greeting: `Hello, ${input.name}!` }),
+    input: inputSchema,
+    output: outputSchema,
+  });
+
+  describe('basics', () => {
+    test('returns correct id', () => {
+      expect(greet.id).toBe('greet');
+    });
+
+    test("returns kind 'trail'", () => {
+      expect(greet.kind).toBe('trail');
+    });
+
+    test('preserves input schema', () => {
+      const parsed = greet.input.safeParse({ name: 'World' });
+      expect(parsed.success).toBe(true);
+
+      const bad = greet.input.safeParse({ name: 42 });
+      expect(bad.success).toBe(false);
+    });
+
+    test('output schema is optional', () => {
+      const minimal = trail('noop', {
+        implementation: () => Result.ok(),
+        input: z.object({}),
+      });
+      expect(minimal.output).toBeUndefined();
+    });
+
+    test('implementation is callable', async () => {
+      const result = await greet.implementation({ name: 'World' }, stubCtx);
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ greeting: 'Hello, World!' });
+    });
+  });
+
+  describe('metadata', () => {
+    test('examples are stored', () => {
+      const withExamples = trail('echo', {
+        examples: [
+          { error: 'ValidationError', input: { text: '' }, name: 'error-case' },
+          { expected: { text: 'hi' }, input: { text: 'hi' }, name: 'basic' },
+        ],
+        implementation: (input) => Result.ok({ text: input.text }),
+        input: z.object({ text: z.string() }),
+      });
+      expect(withExamples.examples).toHaveLength(2);
+      const first = withExamples.examples?.[0];
+      expect(first?.name).toBe('error-case');
+      const second = withExamples.examples?.[1];
+      expect(second?.name).toBe('basic');
+    });
+
+    test('markers are stored', () => {
+      const withMarkers = trail('tagged', {
+        implementation: () => Result.ok(),
+        input: z.object({}),
+        markers: { domain: 'billing', tier: 1 },
+      });
+      expect(withMarkers.markers).toEqual({ domain: 'billing', tier: 1 });
+    });
+
+    test('detours are stored', () => {
+      const withDetours = trail('orchestrator', {
+        detours: {
+          onFailure: ['alert'],
+          onSuccess: ['notify', 'audit'],
+        },
+        implementation: () => Result.ok(),
+        input: z.object({}),
+      });
+      expect(withDetours.detours).toEqual({
+        onFailure: ['alert'],
+        onSuccess: ['notify', 'audit'],
+      });
+    });
+  });
+
+  describe('boolean flags', () => {
+    test('boolean flags default to undefined', () => {
+      const minimal = trail('bare', {
+        implementation: () => Result.ok(),
+        input: z.object({}),
+      });
+      expect(minimal.readOnly).toBeUndefined();
+      expect(minimal.destructive).toBeUndefined();
+      expect(minimal.idempotent).toBeUndefined();
+    });
+
+    test('boolean flags are preserved when set', () => {
+      const withFlags = trail('flagged', {
+        destructive: false,
+        idempotent: true,
+        implementation: () => Result.ok(),
+        input: z.object({}),
+        readOnly: true,
+      });
+      expect(withFlags.readOnly).toBe(true);
+      expect(withFlags.destructive).toBe(false);
+      expect(withFlags.idempotent).toBe(true);
+    });
+  });
+
+  describe('single-object overload', () => {
+    test('accepts spec with id property', () => {
+      const t = trail({
+        id: 'entity.show',
+        implementation: (input: { name: string }, _ctx: TrailContext) =>
+          Result.ok({ greeting: `Hi, ${input.name}` }),
+        input: inputSchema,
+      });
+      expect(t.id).toBe('entity.show');
+      expect(t.kind).toBe('trail');
+    });
+
+    test('preserves all spec fields', () => {
+      const t = trail({
+        description: 'A full trail',
+        destructive: false,
+        examples: [{ input: { name: 'World' }, name: 'test' }],
+        id: 'full',
+        implementation: (input: { name: string }, _ctx: TrailContext) =>
+          Result.ok({ greeting: `Hi, ${input.name}` }),
+        input: inputSchema,
+        output: outputSchema,
+        readOnly: true,
+      });
+      expect(t.description).toBe('A full trail');
+      expect(t.readOnly).toBe(true);
+      expect(t.examples).toHaveLength(1);
+    });
+
+    test('implementation is callable', async () => {
+      const t = trail({
+        id: 'callable',
+        implementation: (input: { x: number }) => Result.ok(input.x * 2),
+        input: z.object({ x: z.number() }),
+      });
+      const result = await t.implementation({ x: 5 }, stubCtx);
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toBe(10);
+    });
+
+    test('sync implementations are normalized to an awaitable runtime function', async () => {
+      const t = trail('normalized', {
+        implementation: (input: { value: number }) =>
+          Result.ok(input.value + 1),
+        input: z.object({ value: z.number() }),
+      });
+
+      const promise = t.implementation({ value: 2 }, stubCtx);
+      expect(promise).toBeInstanceOf(Promise);
+
+      const result = await promise;
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toBe(3);
+    });
+  });
+});