apcore-js 0.5.0 → 0.6.0

package/tests/observability/test-metrics.test.ts

@@ -1,186 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { MetricsCollector, MetricsMiddleware } from '../../src/observability/metrics.js';
-import { Context } from '../../src/context.js';
-import { ModuleError } from '../../src/errors.js';
-
-describe('MetricsCollector', () => {
-  it('increments counters', () => {
-    const collector = new MetricsCollector();
-    collector.increment('test_counter', { method: 'GET' });
-    collector.increment('test_counter', { method: 'GET' });
-    const snap = collector.snapshot();
-    expect((snap['counters'] as Record<string, number>)['test_counter|method=GET']).toBe(2);
-  });
-
-  it('observes histogram values', () => {
-    const collector = new MetricsCollector();
-    collector.observe('test_hist', { module: 'a' }, 0.05);
-    collector.observe('test_hist', { module: 'a' }, 0.5);
-    const snap = collector.snapshot();
-    const hists = snap['histograms'] as Record<string, Record<string, number>>;
-    expect(hists['sums']['test_hist|module=a']).toBeCloseTo(0.55);
-    expect(hists['counts']['test_hist|module=a']).toBe(2);
-  });
-
-  it('convenience methods work', () => {
-    const collector = new MetricsCollector();
-    collector.incrementCalls('mod.a', 'success');
-    collector.incrementErrors('mod.a', 'TIMEOUT');
-    collector.observeDuration('mod.a', 0.1);
-
-    const snap = collector.snapshot();
-    const counters = snap['counters'] as Record<string, number>;
-    expect(counters['apcore_module_calls_total|module_id=mod.a,status=success']).toBe(1);
-    expect(counters['apcore_module_errors_total|error_code=TIMEOUT,module_id=mod.a']).toBe(1);
-  });
-
-  it('reset clears all data', () => {
-    const collector = new MetricsCollector();
-    collector.incrementCalls('mod.a', 'success');
-    collector.observeDuration('mod.a', 0.1);
-    collector.reset();
-    const snap = collector.snapshot();
-    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
-  });
-
-  it('snapshot returns counters and histogram sub-keys', () => {
-    const collector = new MetricsCollector();
-    collector.increment('req_total', { status: '200' });
-    collector.observe('req_duration', { route: '/health' }, 0.01);
-    const snap = collector.snapshot();
-    expect(snap).toHaveProperty('counters');
-    expect(snap).toHaveProperty('histograms');
-    const hists = snap['histograms'] as Record<string, unknown>;
-    expect(hists).toHaveProperty('sums');
-    expect(hists).toHaveProperty('counts');
-    expect(hists).toHaveProperty('buckets');
-  });
-
-  it('exportPrometheus produces valid format', () => {
-    const collector = new MetricsCollector();
-    collector.incrementCalls('mod.a', 'success');
-    collector.observeDuration('mod.a', 0.05);
-    const output = collector.exportPrometheus();
-    expect(output).toContain('# HELP');
-    expect(output).toContain('# TYPE');
-    expect(output).toContain('apcore_module_calls_total');
-    expect(output).toContain('apcore_module_duration_seconds');
-  });
-
-  it('empty collector returns empty prometheus string', () => {
-    const collector = new MetricsCollector();
-    expect(collector.exportPrometheus()).toBe('');
-  });
-
-  it('accepts custom buckets and uses them for observations', () => {
-    const collector = new MetricsCollector([0.1, 0.5, 1.0]);
-    collector.observe('custom_hist', { op: 'read' }, 0.3);
-    const snap = collector.snapshot();
-    const hists = snap['histograms'] as Record<string, Record<string, number>>;
-    // value 0.3 falls in the 0.5 bucket but not 0.1
-    expect(hists['buckets']['custom_hist|op=read|0.1']).toBeUndefined();
-    expect(hists['buckets']['custom_hist|op=read|0.5']).toBe(1);
-    expect(hists['buckets']['custom_hist|op=read|Inf']).toBe(1);
-  });
-
-  it('exportPrometheus omits label braces when metric has no labels', () => {
-    const collector = new MetricsCollector();
-    // increment with empty labels so parseLabels receives '' and formatLabels receives {}
-    collector.increment('no_label_counter', {});
-    const output = collector.exportPrometheus();
-    expect(output).toContain('no_label_counter 1');
-    expect(output).not.toContain('no_label_counter{');
-  });
-});
-
-describe('MetricsMiddleware', () => {
-  it('records call metrics on success', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.after('mod.a', {}, { result: 'ok' }, ctx);
-
-    const snap = collector.snapshot();
-    const counters = snap['counters'] as Record<string, number>;
-    expect(counters['apcore_module_calls_total|module_id=mod.a,status=success']).toBe(1);
-  });
-
-  it('records error metrics on failure with plain Error', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.onError('mod.a', {}, new Error('boom'), ctx);
-
-    const snap = collector.snapshot();
-    const counters = snap['counters'] as Record<string, number>;
-    expect(counters['apcore_module_calls_total|module_id=mod.a,status=error']).toBe(1);
-    expect(counters['apcore_module_errors_total|error_code=Error,module_id=mod.a']).toBe(1);
-  });
-
-  it('records error code from ModuleError.code instead of constructor name', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = Context.create();
-
-    mw.before('mod.b', {}, ctx);
-    mw.onError('mod.b', {}, new ModuleError('CUSTOM_CODE', 'something went wrong'), ctx);
-
-    const snap = collector.snapshot();
-    const counters = snap['counters'] as Record<string, number>;
-    expect(counters['apcore_module_errors_total|error_code=CUSTOM_CODE,module_id=mod.b']).toBe(1);
-  });
-
-  it('after() returns null without recording metrics when starts is undefined', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = new Context('trace-id', null, [], null, null);
-
-    const result = mw.after('mod.a', {}, { result: 'ok' }, ctx);
-
-    expect(result).toBeNull();
-    const snap = collector.snapshot();
-    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
-  });
-
-  it('after() returns null without recording metrics when starts array is empty', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = new Context('trace-id', null, [], null, null);
-    ctx.data['_metrics_starts'] = [];
-
-    const result = mw.after('mod.a', {}, { result: 'ok' }, ctx);
-
-    expect(result).toBeNull();
-    const snap = collector.snapshot();
-    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
-  });
-
-  it('onError() returns null without recording metrics when starts is undefined', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = new Context('trace-id', null, [], null, null);
-
-    const result = mw.onError('mod.a', {}, new Error('boom'), ctx);
-
-    expect(result).toBeNull();
-    const snap = collector.snapshot();
-    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
-  });
-
-  it('onError() returns null without recording metrics when starts array is empty', () => {
-    const collector = new MetricsCollector();
-    const mw = new MetricsMiddleware(collector);
-    const ctx = new Context('trace-id', null, [], null, null);
-    ctx.data['_metrics_starts'] = [];
-
-    const result = mw.onError('mod.a', {}, new Error('boom'), ctx);
-
-    expect(result).toBeNull();
-    const snap = collector.snapshot();
-    expect(Object.keys(snap['counters'] as Record<string, unknown>)).toHaveLength(0);
-  });
-});

package/tests/observability/test-tracing.test.ts

@@ -1,303 +0,0 @@
-import { describe, it, expect, vi, afterEach } from 'vitest';
-import { Context } from '../../src/context.js';
-import {
-  createSpan,
-  InMemoryExporter,
-  OTLPExporter,
-  StdoutExporter,
-  TracingMiddleware,
-} from '../../src/observability/tracing.js';
-
-describe('Span', () => {
-  it('createSpan creates span with defaults', () => {
-    const span = createSpan({
-      traceId: 'trace-1',
-      name: 'test.span',
-      startTime: 100,
-    });
-    expect(span.traceId).toBe('trace-1');
-    expect(span.name).toBe('test.span');
-    expect(span.startTime).toBe(100);
-    expect(span.spanId).toBeDefined();
-    expect(span.parentSpanId).toBeNull();
-    expect(span.status).toBe('ok');
-    expect(span.events).toEqual([]);
-  });
-});
-
-describe('InMemoryExporter', () => {
-  it('collects and retrieves spans', () => {
-    const exporter = new InMemoryExporter();
-    const span = createSpan({ traceId: 't1', name: 'test', startTime: 0 });
-    exporter.export(span);
-    expect(exporter.getSpans()).toHaveLength(1);
-    expect(exporter.getSpans()[0].traceId).toBe('t1');
-  });
-
-  it('respects max_spans limit', () => {
-    const exporter = new InMemoryExporter(3);
-    for (let i = 0; i < 5; i++) {
-      exporter.export(createSpan({ traceId: `t${i}`, name: 'test', startTime: i }));
-    }
-    const spans = exporter.getSpans();
-    expect(spans).toHaveLength(3);
-    expect(spans[0].traceId).toBe('t2');
-  });
-
-  it('clear removes all spans', () => {
-    const exporter = new InMemoryExporter();
-    exporter.export(createSpan({ traceId: 't1', name: 'test', startTime: 0 }));
-    exporter.clear();
-    expect(exporter.getSpans()).toHaveLength(0);
-  });
-});
-
-describe('TracingMiddleware', () => {
-  it('creates and exports spans on success', () => {
-    const exporter = new InMemoryExporter();
-    const mw = new TracingMiddleware(exporter);
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.after('mod.a', {}, { result: 'ok' }, ctx);
-
-    const spans = exporter.getSpans();
-    expect(spans).toHaveLength(1);
-    expect(spans[0].name).toBe('apcore.module.execute');
-    expect(spans[0].status).toBe('ok');
-    expect(spans[0].attributes['moduleId']).toBe('mod.a');
-  });
-
-  it('creates error spans', () => {
-    const exporter = new InMemoryExporter();
-    const mw = new TracingMiddleware(exporter);
-    const ctx = Context.create();
-
-    mw.before('mod.err', {}, ctx);
-    mw.onError('mod.err', {}, new Error('fail'), ctx);
-
-    const spans = exporter.getSpans();
-    expect(spans).toHaveLength(1);
-    expect(spans[0].status).toBe('error');
-  });
-
-  it('supports nested spans with parent chain', () => {
-    const exporter = new InMemoryExporter();
-    const mw = new TracingMiddleware(exporter);
-    const ctx = Context.create();
-
-    mw.before('mod.outer', {}, ctx);
-    mw.before('mod.inner', {}, ctx);
-    mw.after('mod.inner', {}, {}, ctx);
-    mw.after('mod.outer', {}, {}, ctx);
-
-    const spans = exporter.getSpans();
-    expect(spans).toHaveLength(2);
-    // inner span has outer as parent
-    expect(spans[0].parentSpanId).toBe(spans[1].spanId);
-  });
-
-  it('off strategy does not export', () => {
-    const exporter = new InMemoryExporter();
-    const mw = new TracingMiddleware(exporter, 1.0, 'off');
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.after('mod.a', {}, {}, ctx);
-
-    expect(exporter.getSpans()).toHaveLength(0);
-  });
-
-  it('error_first exports errors even when not sampled', () => {
-    const exporter = new InMemoryExporter();
-    const mw = new TracingMiddleware(exporter, 0.0, 'error_first');
-    const ctx = Context.create();
-
-    mw.before('mod.a', {}, ctx);
-    mw.onError('mod.a', {}, new Error('fail'), ctx);
-
-    expect(exporter.getSpans()).toHaveLength(1);
-  });
-
-  it('throws on invalid sampling rate', () => {
-    const exporter = new InMemoryExporter();
-    expect(() => new TracingMiddleware(exporter, -0.1)).toThrow();
-    expect(() => new TracingMiddleware(exporter, 1.5)).toThrow();
-  });
-
-  it('throws on invalid sampling strategy', () => {
-    const exporter = new InMemoryExporter();
-    expect(() => new TracingMiddleware(exporter, 1.0, 'invalid')).toThrow();
-  });
-
-  describe('setExporter', () => {
-    it('rejects null exporter', () => {
-      const mw = new TracingMiddleware(new InMemoryExporter());
-      expect(() => mw.setExporter(null as any)).toThrow('exporter must implement SpanExporter interface');
-    });
-
-    it('rejects object without export method', () => {
-      const mw = new TracingMiddleware(new InMemoryExporter());
-      expect(() => mw.setExporter({} as any)).toThrow('exporter must implement SpanExporter interface');
-    });
-
-    it('accepts valid exporter', () => {
-      const mw = new TracingMiddleware(new InMemoryExporter());
-      const newExporter = { export: () => {} };
-      expect(() => mw.setExporter(newExporter)).not.toThrow();
-    });
-  });
-});
-
-describe('OTLPExporter', () => {
-  const originalFetch = globalThis.fetch;
-
-  afterEach(() => {
-    globalThis.fetch = originalFetch;
-  });
-
-  function makeTestSpan() {
-    return createSpan({
-      traceId: 'trace-abc',
-      name: 'test.op',
-      startTime: 1000,
-      spanId: 'span-123',
-      parentSpanId: 'parent-456',
-      attributes: { foo: 'bar' },
-    });
-  }
-
-  it('calls fetch with correct URL and payload shape', async () => {
-    const mockFetch = vi.fn().mockResolvedValue(new Response('ok'));
-    globalThis.fetch = mockFetch;
-
-    const exporter = new OTLPExporter();
-    const span = makeTestSpan();
-    span.endTime = 2000;
-    span.status = 'ok';
-    exporter.export(span);
-
-    // Wait for the fire-and-forget promise
-    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalledTimes(1));
-
-    const [url, options] = mockFetch.mock.calls[0];
-    expect(url).toBe('http://localhost:4318/v1/traces');
-    expect(options.method).toBe('POST');
-    expect(options.headers['Content-Type']).toBe('application/json');
-
-    const body = JSON.parse(options.body);
-    expect(body.resourceSpans).toHaveLength(1);
-    expect(body.resourceSpans[0].resource.attributes[0].key).toBe('service.name');
-    expect(body.resourceSpans[0].resource.attributes[0].value.stringValue).toBe('apcore');
-
-    const exportedSpan = body.resourceSpans[0].scopeSpans[0].spans[0];
-    expect(exportedSpan.traceId).toBe('trace-abc');
-    expect(exportedSpan.spanId).toBe('span-123');
-    expect(exportedSpan.parentSpanId).toBe('parent-456');
-    expect(exportedSpan.name).toBe('test.op');
-    expect(exportedSpan.status.code).toBe(1);
-    expect(exportedSpan.attributes).toEqual([
-      { key: 'foo', value: { stringValue: 'bar' } },
-    ]);
-  });
-
-  it('uses default endpoint when none provided', () => {
-    const mockFetch = vi.fn().mockResolvedValue(new Response('ok'));
-    globalThis.fetch = mockFetch;
-
-    const exporter = new OTLPExporter();
-    exporter.export(makeTestSpan());
-
-    expect(mockFetch).toHaveBeenCalledTimes(1);
-    expect(mockFetch.mock.calls[0][0]).toBe('http://localhost:4318/v1/traces');
-  });
-
-  it('uses custom endpoint when provided', () => {
-    const mockFetch = vi.fn().mockResolvedValue(new Response('ok'));
-    globalThis.fetch = mockFetch;
-
-    const exporter = new OTLPExporter({ endpoint: 'http://custom:9999/traces' });
-    exporter.export(makeTestSpan());
-
-    expect(mockFetch).toHaveBeenCalledTimes(1);
-    expect(mockFetch.mock.calls[0][0]).toBe('http://custom:9999/traces');
-  });
-
-  it('includes custom headers in fetch call', () => {
-    const mockFetch = vi.fn().mockResolvedValue(new Response('ok'));
-    globalThis.fetch = mockFetch;
-
-    const exporter = new OTLPExporter({
-      headers: { 'X-Api-Key': 'secret-key', 'X-Custom': 'value' },
-    });
-    exporter.export(makeTestSpan());
-
-    const headers = mockFetch.mock.calls[0][1].headers;
-    expect(headers['X-Api-Key']).toBe('secret-key');
-    expect(headers['X-Custom']).toBe('value');
-    expect(headers['Content-Type']).toBe('application/json');
-  });
-
-  it('silently catches network errors', async () => {
-    const mockFetch = vi.fn().mockRejectedValue(new Error('network down'));
-    globalThis.fetch = mockFetch;
-
-    const exporter = new OTLPExporter();
-    // Should not throw
-    expect(() => exporter.export(makeTestSpan())).not.toThrow();
-
-    // Wait for the rejected promise to be caught
-    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalledTimes(1));
-  });
-
-  it('converts timestamps to nanoseconds in OTLP payload', async () => {
-    const mockFetch = vi.fn().mockResolvedValue(new Response('ok'));
-    globalThis.fetch = mockFetch;
-
-    const exporter = new OTLPExporter();
-    const span = createSpan({
-      traceId: 'trace-ns',
-      name: 'ns.test',
-      startTime: 1700000000.123,
-      spanId: 'span-ns',
-    });
-    span.endTime = 1700000002.456;
-    exporter.export(span);
-
-    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalledTimes(1));
-
-    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
-    const exportedSpan = body.resourceSpans[0].scopeSpans[0].spans[0];
-
-    // startTime 1700000000.123 * 1_000_000_000 = 1700000000123000000
-    const expectedStartNano = String(Math.round(1700000000.123 * 1_000_000_000));
-    expect(exportedSpan.startTimeUnixNano).toBe(expectedStartNano);
-
-    // endTime 1700000002.456 * 1_000_000_000 = 1700000002456000000
-    const expectedEndNano = String(Math.round(1700000002.456 * 1_000_000_000));
-    expect(exportedSpan.endTimeUnixNano).toBe(expectedEndNano);
-  });
-
-  it('omits endTimeUnixNano when endTime is null', async () => {
-    const mockFetch = vi.fn().mockResolvedValue(new Response('ok'));
-    globalThis.fetch = mockFetch;
-
-    const exporter = new OTLPExporter();
-    const span = createSpan({
-      traceId: 'trace-no-end',
-      name: 'no.end',
-      startTime: 1700000000,
-      spanId: 'span-no-end',
-    });
-    // endTime is null by default
-    exporter.export(span);
-
-    await vi.waitFor(() => expect(mockFetch).toHaveBeenCalledTimes(1));
-
-    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
-    const exportedSpan = body.resourceSpans[0].scopeSpans[0].spans[0];
-
-    expect(exportedSpan.startTimeUnixNano).toBe(String(Math.round(1700000000 * 1_000_000_000)));
-    expect(exportedSpan.endTimeUnixNano).toBeUndefined();
-  });
-});

package/tests/registry/test-dependencies.test.ts

@@ -1,70 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { resolveDependencies } from '../../src/registry/dependencies.js';
-import { CircularDependencyError, ModuleLoadError } from '../../src/errors.js';
-
-describe('resolveDependencies', () => {
-  it('returns empty for empty input', () => {
-    expect(resolveDependencies([])).toEqual([]);
-  });
-
-  it('returns single module', () => {
-    const result = resolveDependencies([['mod.a', []]]);
-    expect(result).toEqual(['mod.a']);
-  });
-
-  it('resolves linear dependency chain', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.b', [{ moduleId: 'mod.a', optional: false, version: null }]],
-      ['mod.a', []],
-    ];
-    const result = resolveDependencies(modules);
-    expect(result.indexOf('mod.a')).toBeLessThan(result.indexOf('mod.b'));
-  });
-
-  it('resolves diamond dependency', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.d', [{ moduleId: 'mod.b', optional: false, version: null }, { moduleId: 'mod.c', optional: false, version: null }]],
-      ['mod.b', [{ moduleId: 'mod.a', optional: false, version: null }]],
-      ['mod.c', [{ moduleId: 'mod.a', optional: false, version: null }]],
-      ['mod.a', []],
-    ];
-    const result = resolveDependencies(modules);
-    expect(result.indexOf('mod.a')).toBeLessThan(result.indexOf('mod.b'));
-    expect(result.indexOf('mod.a')).toBeLessThan(result.indexOf('mod.c'));
-    expect(result.indexOf('mod.b')).toBeLessThan(result.indexOf('mod.d'));
-    expect(result.indexOf('mod.c')).toBeLessThan(result.indexOf('mod.d'));
-  });
-
-  it('throws CircularDependencyError on cycle', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.a', [{ moduleId: 'mod.b', optional: false, version: null }]],
-      ['mod.b', [{ moduleId: 'mod.a', optional: false, version: null }]],
-    ];
-    expect(() => resolveDependencies(modules)).toThrow(CircularDependencyError);
-  });
-
-  it('throws ModuleLoadError for missing required dependency', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.a', [{ moduleId: 'mod.missing', optional: false, version: null }]],
-    ];
-    expect(() => resolveDependencies(modules)).toThrow(ModuleLoadError);
-  });
-
-  it('skips optional missing dependencies', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.a', [{ moduleId: 'mod.missing', optional: true, version: null }]],
-    ];
-    const result = resolveDependencies(modules);
-    expect(result).toEqual(['mod.a']);
-  });
-
-  it('independent modules in deterministic order', () => {
-    const modules: Array<[string, Array<{ moduleId: string; optional: boolean; version: string | null }>]> = [
-      ['mod.c', []],
-      ['mod.a', []],
-      ['mod.b', []],
-    ];
-    const result = resolveDependencies(modules);
-    expect(result).toEqual(['mod.a', 'mod.b', 'mod.c']);
-  });
-});