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

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-config.test.ts

@@ -0,0 +1,224 @@
+/* oxlint-disable require-await -- trail implementations satisfy async interface without awaiting */
+import { describe, expect, test } from 'bun:test';
+
+import { z } from 'zod';
+
+import { executeTrail } from '../execute.js';
+import { Result } from '../result.js';
+import { service } from '../service.js';
+import { trail } from '../trail.js';
+import type { ServiceContext } from '../service.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const nextId = (name: string): string =>
+  `test.svc-config.${name}.${Bun.randomUUIDv7()}`;
+
+const createSingletonConfigTrail = (id: string) => {
+  const captures = { createCalls: 0 };
+  const svc = service(id, {
+    config: z.object({ key: z.string() }),
+    create: (ctx: ServiceContext<{ key: string }>) => {
+      captures.createCalls += 1;
+      return Result.ok({
+        createCall: captures.createCalls,
+        key: ctx.config.key,
+      });
+    },
+  });
+
+  return {
+    captures,
+    trail: trail('svc-config.singleton', {
+      input: z.object({}),
+      output: z.object({ createCall: z.number(), key: z.string() }),
+      run: (_input, ctx) =>
+        Result.ok({
+          createCall: svc.from(ctx).createCall,
+          key: svc.from(ctx).key,
+        }),
+      services: [svc],
+    }),
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('ServiceContext.config', () => {
+  test('service with config schema receives validated config in svc.config', async () => {
+    const id = nextId('typed-config');
+    let capturedConfig: unknown;
+
+    const db = service(id, {
+      config: z.object({ poolSize: z.number(), url: z.string().url() }),
+      create: (svc: ServiceContext<{ url: string; poolSize: number }>) => {
+        capturedConfig = svc.config;
+        return Result.ok({ connected: true });
+      },
+    });
+
+    const dbTrail = trail('svc-config.typed', {
+      input: z.object({}),
+      output: z.object({ connected: z.boolean() }),
+      run: (_input, ctx) => Result.ok({ connected: db.from(ctx).connected }),
+      services: [db],
+    });
+
+    const result = await executeTrail(
+      dbTrail,
+      {},
+      {
+        configValues: {
+          [id]: { poolSize: 5, url: 'https://example.com' },
+        },
+      }
+    );
+
+    expect(result.isOk()).toBe(true);
+    expect(capturedConfig).toEqual({ poolSize: 5, url: 'https://example.com' });
+  });
+
+  test('service without config still works — svc.config is undefined', async () => {
+    const id = nextId('no-config');
+    let capturedConfig: unknown = 'sentinel';
+
+    const counter = service(id, {
+      create: (svc) => {
+        capturedConfig = svc.config;
+        return Result.ok(42);
+      },
+    });
+
+    const counterTrail = trail('svc-config.no-config', {
+      input: z.object({}),
+      run: (_input, ctx) => Result.ok({ value: counter.from(ctx) }),
+      services: [counter],
+    });
+
+    const result = await executeTrail(counterTrail, {});
+
+    expect(result.isOk()).toBe(true);
+    expect(capturedConfig).toBeUndefined();
+  });
+
+  test('config validation failure returns Result.err at service creation time', async () => {
+    const id = nextId('invalid-config');
+
+    const db = service(id, {
+      config: z.object({ url: z.string().url() }),
+      create: () => Result.ok({ connected: true }),
+    });
+
+    const dbTrail = trail('svc-config.invalid', {
+      input: z.object({}),
+      run: () => Result.ok(null),
+      services: [db],
+    });
+
+    const result = await executeTrail(
+      dbTrail,
+      {},
+      {
+        configValues: {
+          [id]: { url: 'not-a-url' },
+        },
+      }
+    );
+
+    expect(result.isErr()).toBe(true);
+    expect(result.error.message).toContain(id);
+  });
+
+  test('missing configValues for a service with config schema returns Result.err', async () => {
+    const id = nextId('missing-config');
+
+    const db = service(id, {
+      config: z.object({ url: z.string().url() }),
+      create: () => Result.ok({ connected: true }),
+    });
+
+    const dbTrail = trail('svc-config.missing', {
+      input: z.object({}),
+      run: () => Result.ok(null),
+      services: [db],
+    });
+
+    const result = await executeTrail(dbTrail, {});
+
+    expect(result.isErr()).toBe(true);
+    expect(result.error.message).toContain(id);
+  });
+
+  test('service override bypasses config validation', async () => {
+    const id = nextId('override-bypass');
+
+    const db = service(id, {
+      config: z.object({ url: z.string().url() }),
+      create: () => Result.ok({ connected: true }),
+    });
+
+    const dbTrail = trail('svc-config.override', {
+      input: z.object({}),
+      output: z.object({ value: z.number() }),
+      run: (_input, ctx) => Result.ok({ value: db.from(ctx) as number }),
+      services: [db],
+    });
+
+    // Provide the service via overrides without any configValues — should NOT fail
+    const result = await executeTrail(dbTrail, {}, { services: { [id]: 42 } });
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ value: 42 });
+  });
+  test('config values passed through ExecuteTrailOptions.configValues', async () => {
+    const id = nextId('options-config');
+    const captures: unknown[] = [];
+
+    const svc = service(id, {
+      config: z.object({ key: z.string() }),
+      create: (ctx: ServiceContext<{ key: string }>) => {
+        captures.push(ctx.config);
+        return Result.ok({ key: ctx.config.key });
+      },
+    });
+
+    const svcTrail = trail('svc-config.options', {
+      input: z.object({}),
+      output: z.object({ key: z.string() }),
+      run: (_input, ctx) => Result.ok({ key: svc.from(ctx).key }),
+      services: [svc],
+    });
+
+    const result = await executeTrail(
+      svcTrail,
+      {},
+      {
+        configValues: { [id]: { key: 'hello' } },
+      }
+    );
+
+    expect(result.isOk()).toBe(true);
+    expect(result.unwrap()).toEqual({ key: 'hello' });
+    expect(captures).toEqual([{ key: 'hello' }]);
+  });
+
+  test('config-aware singleton services reuse the cached instance', async () => {
+    const id = nextId('singleton-config');
+    const { captures, trail: singletonTrail } = createSingletonConfigTrail(id);
+    const options = {
+      configValues: { [id]: { key: 'hello' } },
+    };
+    const first = await executeTrail(singletonTrail, {}, options);
+    const second = await executeTrail(singletonTrail, {}, options);
+
+    expect(first.isOk()).toBe(true);
+    expect(second.isOk()).toBe(true);
+    expect(first.unwrap()).toEqual({ createCall: 1, key: 'hello' });
+    expect(second.unwrap()).toEqual({ createCall: 1, key: 'hello' });
+    expect(captures.createCalls).toBe(1);
+  });
+});