@ontrails/core 1.0.0-beta.10 → 1.0.0-beta.11

package/src/__tests__/execute.test.ts

@@ -8,8 +8,9 @@ import { executeTrail } from '../execute';
 import { createTrailContext } from '../context';
 import type { Layer } from '../layer';
 import { Result } from '../result';
+import { service } from '../service';
 import { trail } from '../trail';
-import type { TrailContext } from '../types';
+import type { TrailContext, TrailContextInit } from '../types';
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -33,6 +34,76 @@ const throwingTrail = trail('throws', {
   },
 });
 
+const nextServiceId = (name: string): string =>
+  `test.service.${name}.${Bun.randomUUIDv7()}`;
+
+const createResolvedValueService = (
+  id: string,
+  onCreate: () => void,
+  value: number
+) =>
+  service(id, {
+    create: () => {
+      onCreate();
+      return Result.ok({ value });
+    },
+  });
+
+const createEagerServiceTrail = (
+  id: string,
+  counter: ReturnType<typeof createResolvedValueService>,
+  onRun: (value: number) => void
+) =>
+  trail('service.eager', {
+    input: z.object({}),
+    output: z.object({ total: z.number() }),
+    run: (_input, ctx) => {
+      const fromAccessor = ctx.service<{ value: number }>(id);
+      const fromDefinition = counter.from(ctx);
+      onRun(fromDefinition.value);
+      return Result.ok({ total: fromAccessor.value + 1 });
+    },
+    services: [counter],
+  });
+
+const createServiceProbeLayer = (
+  counter: ReturnType<typeof createResolvedValueService>,
+  onResolve: (value: number) => void
+): Layer => ({
+  name: 'uses-service',
+  wrap(_trail, impl) {
+    return async (input, ctx) => {
+      onResolve(ctx.service<{ value: number }>(counter).value);
+      return await impl(input, ctx);
+    };
+  },
+});
+
+const createSingletonService = (id: string, onCreate: () => number) =>
+  service(id, {
+    create: () => Result.ok({ createdAtCall: onCreate() }),
+  });
+
+const createSingletonTrail = (
+  singleton: ReturnType<typeof createSingletonService>
+) =>
+  trail('service.singleton', {
+    input: z.object({}),
+    output: z.object({ createdAtCall: z.number() }),
+    run: (_input, ctx) =>
+      Result.ok({
+        createdAtCall: singleton.from(ctx).createdAtCall,
+      }),
+    services: [singleton],
+  });
+
+const unwrapExecution = async (
+  target: ReturnType<typeof createSingletonTrail>
+) => {
+  const result = await executeTrail(target, {});
+  return result.unwrap();
+};
+
 // ---------------------------------------------------------------------------
 // Tests
 // ---------------------------------------------------------------------------
@@ -45,6 +116,112 @@ describe('executeTrail', () => {
       expect(result.isOk()).toBe(true);
       expect(result.unwrap()).toEqual({ value: 'hello' });
     });
+
+    test('eagerly resolves declared services before layers and implementation run', async () => {
+      const id = nextServiceId('eager');
+      const captures = {
+        createCalls: 0,
+        layerResolved: undefined as number | undefined,
+        runResolved: undefined as number | undefined,
+      };
+      const counter = createResolvedValueService(
+        id,
+        () => {
+          captures.createCalls += 1;
+        },
+        41
+      );
+      const layeredTrail = createEagerServiceTrail(id, counter, (value) => {
+        captures.runResolved = value;
+      });
+      const layer = createServiceProbeLayer(counter, (value) => {
+        captures.layerResolved = value;
+      });
+
+      const result = await executeTrail(layeredTrail, {}, { layers: [layer] });
+
+      expect(result.unwrap()).toEqual({ total: 42 });
+      expect(captures.createCalls).toBe(1);
+      expect(captures.layerResolved).toBe(41);
+      expect(captures.runResolved).toBe(41);
+    });
+
+    test('awaits async service factories before running the trail', async () => {
+      const db = service(nextServiceId('async-factory'), {
+        create: async () => {
+          await Bun.sleep(0);
+          return Result.ok({ source: 'async-factory' });
+        },
+      });
+      const serviceTrail = trail('service.async-factory', {
+        input: z.object({}),
+        output: z.object({ source: z.string() }),
+        run: (_input, ctx) =>
+          Result.ok({ source: db.from(ctx).source as string }),
+        services: [db],
+      });
+
+      const result = await executeTrail(serviceTrail, {});
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ source: 'async-factory' });
+    });
+
+    test('reuses cached singleton services across executions', async () => {
+      const id = nextServiceId('singleton');
+      const captures = { createCalls: 0 };
+      const singleton = createSingletonService(id, () => {
+        captures.createCalls += 1;
+        return captures.createCalls;
+      });
+      const singletonTrail = createSingletonTrail(singleton);
+
+      const outputs = [
+        await unwrapExecution(singletonTrail),
+        await unwrapExecution(singletonTrail),
+      ];
+
+      expect(outputs).toEqual([{ createdAtCall: 1 }, { createdAtCall: 1 }]);
+      expect(captures.createCalls).toBe(1);
+    });
+
+    test('scopes cached singleton services to compatible service contexts', async () => {
+      const id = nextServiceId('singleton-context');
+      const envAwareService = service(id, {
+        create: (ctx) => Result.ok({ value: String(ctx.env?.VAL) }),
+      });
+      const envAwareTrail = trail('service.singleton-context', {
+        input: z.object({}),
+        output: z.object({ value: z.string() }),
+        run: (_input, ctx) =>
+          Result.ok({ value: envAwareService.from(ctx).value }),
+        services: [envAwareService],
+      });
+
+      const first = await executeTrail(
+        envAwareTrail,
+        {},
+        {
+          createContext: () =>
+            createTrailContext({
+              env: { VAL: 'first' },
+            }),
+        }
+      );
+      const second = await executeTrail(
+        envAwareTrail,
+        {},
+        {
+          createContext: () =>
+            createTrailContext({
+              env: { VAL: 'second' },
+            }),
+        }
+      );
+
+      expect(first.unwrap()).toEqual({ value: 'first' });
+      expect(second.unwrap()).toEqual({ value: 'second' });
+    });
   });
 
   describe('validation', () => {
@@ -124,7 +301,7 @@ describe('executeTrail', () => {
         },
       });
 
-      const customCtx: TrailContext = {
+      const customCtx: TrailContextInit = {
         cwd: '/custom',
         requestId: 'factory-id',
         signal: new AbortController().signal,
@@ -146,7 +323,7 @@ describe('executeTrail', () => {
         },
       });
 
-      const baseCtx: TrailContext = {
+      const baseCtx: TrailContextInit = {
         cwd: '/factory',
         requestId: 'factory-id',
         signal: new AbortController().signal,
@@ -186,6 +363,71 @@ describe('executeTrail', () => {
       );
       expect(captured?.extensions).toEqual({ store: 'db', userId: '123' });
     });
+
+    test('rebinds ctx.service after merging extension overrides from createContext', async () => {
+      let resolvedSource: string | undefined;
+      const db = service(nextServiceId('context-override'), {
+        create: () => Result.ok({ source: 'factory' }),
+      });
+      const serviceTrail = trail('ctx.service.override', {
+        input: z.object({}),
+        output: z.object({ source: z.string() }),
+        run: (_input, ctx) => {
+          resolvedSource = ctx.service<{ source: string }>(db).source;
+          return Result.ok({ source: resolvedSource });
+        },
+        services: [db],
+      });
+
+      const result = await executeTrail(
+        serviceTrail,
+        {},
+        {
+          createContext: () =>
+            createTrailContext({
+              extensions: {
+                [db.id]: { source: 'factory-context' },
+              },
+            }),
+          ctx: {
+            extensions: {
+              [db.id]: { source: 'override-context' },
+            },
+          },
+        }
+      );
+
+      expect(result.unwrap()).toEqual({ source: 'override-context' });
+      expect(resolvedSource).toBe('override-context');
+    });
+
+    test('context factory seeds the service accessor when omitted', async () => {
+      let capturedCtx: TrailContext | undefined;
+      const id = nextServiceId('factory-seed');
+      const widget = { id: 'widget-1' };
+      const widgetTrail = trail('service.factory-seed', {
+        input: z.object({}),
+        run: (_input, ctx) => {
+          capturedCtx = ctx;
+          return Result.ok(null);
+        },
+        services: [],
+      });
+
+      await executeTrail(
+        widgetTrail,
+        {},
+        {
+          createContext: () => ({
+            extensions: { [id]: widget },
+            requestId: 'seeded-service',
+            signal: new AbortController().signal,
+          }),
+        }
+      );
+
+      expect(capturedCtx?.service(id)).toBe(widget);
+    });
   });
 
   describe('error handling', () => {
@@ -204,5 +446,78 @@ describe('executeTrail', () => {
       expect(result.error).toBeInstanceOf(InternalError);
       expect(result.error.message).toBe('kaboom');
     });
+
+    test('short-circuits when a service factory returns Result.err', async () => {
+      const failingService = service(nextServiceId('factory-error'), {
+        create: () =>
+          Result.err(new ValidationError('DATABASE_URL is required')),
+      });
+      let ran = false;
+      const serviceTrail = trail('service.factory-error', {
+        input: z.object({}),
+        run: () => {
+          ran = true;
+          return Result.ok(null);
+        },
+        services: [failingService],
+      });
+
+      const result = await executeTrail(serviceTrail, {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(ValidationError);
+      expect(result.error.message).toBe('DATABASE_URL is required');
+      expect(ran).toBe(false);
+    });
+
+    test('wraps thrown service factory exceptions with the service ID in context', async () => {
+      const explodingService = service(nextServiceId('factory-throw'), {
+        create: () => {
+          throw new Error('boom');
+        },
+      });
+      const serviceTrail = trail('service.factory-throw', {
+        input: z.object({}),
+        run: () => Result.ok(null),
+        services: [explodingService],
+      });
+
+      const result = await executeTrail(serviceTrail, {});
+
+      expect(result.isErr()).toBe(true);
+      expect(result.error).toBeInstanceOf(InternalError);
+      expect(result.error.message).toContain(explodingService.id);
+      expect(result.error.context).toEqual({ serviceId: explodingService.id });
+    });
+
+    test('prefers explicit service overrides over cached or created instances', async () => {
+      const id = nextServiceId('override');
+      let createCalls = 0;
+      const db = service(id, {
+        create: () => {
+          createCalls += 1;
+          return Result.ok({ source: 'factory' });
+        },
+      });
+      const serviceTrail = trail('service.override', {
+        input: z.object({}),
+        output: z.object({ source: z.string() }),
+        run: (_input, ctx) =>
+          Result.ok({ source: db.from(ctx).source as string }),
+        services: [db],
+      });
+
+      const result = await executeTrail(
+        serviceTrail,
+        {},
+        {
+          services: { [id]: { source: 'override' } },
+        }
+      );
+
+      expect(result.isOk()).toBe(true);
+      expect(result.unwrap()).toEqual({ source: 'override' });
+      expect(createCalls).toBe(0);
+    });
   });
 });

package/src/__tests__/layer.test.ts

@@ -3,16 +3,17 @@ import { describe, test, expect } from 'bun:test';
 
 import { z } from 'zod';
 
+import { createTrailContext } from '../context';
 import { composeLayers } from '../layer';
 import type { Layer } from '../layer';
 import { Result } from '../result';
 import { trail } from '../trail';
 import type { TrailContext } from '../types';
 
-const stubCtx: TrailContext = {
+const stubCtx: TrailContext = createTrailContext({
   requestId: 'test-layer',
   signal: AbortSignal.timeout(5000),
-};
+});
 
 const echoTrail = trail('echo', {
   input: z.object({ value: z.string() }),

package/src/__tests__/service.test.ts

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