@smoothbricks/lmao 0.1.0

package/src/lib/__tests__/traceContext-type-enforcement.test.ts

@@ -0,0 +1,271 @@
+/**
+ * Type-level tests for Tracer.trace() required/optional property enforcement
+ *
+ * These tests verify that TypeScript properly enforces required vs optional
+ * properties in Tracer.trace() based on the ctx type definition.
+ *
+ * Per spec 01l_module_builder_pattern.md (updated for Op-centric API):
+ * - Properties with `null as Type` in ctx are REQUIRED in trace() options
+ * - Properties with `undefined as Type | undefined` are OPTIONAL in trace() options
+ * - Properties with values are optional with defaults
+ */
+
+import { describe, expect, it } from 'bun:test';
+// Must import test-helpers first to initialize timestamp implementation
+import './test-helpers.js';
+import { S } from '@smoothbricks/arrow-builder';
+import { defineOpContext } from '../defineOpContext.js';
+import { defineLogSchema } from '../schema/defineLogSchema.js';
+import { TestTracer } from '../tracers/TestTracer.js';
+import { createTestTracerOptions } from './test-helpers.js';
+
+// =============================================================================
+// Test Factory Definitions
+// =============================================================================
+
+// Factory with required and optional ctx properties
+const testCtxDefaults: {
+  env: { apiTimeout: number; region: string } | null;
+  requestId: string | null;
+  userId: string | undefined;
+} = {
+  env: null,
+  requestId: null,
+  userId: undefined,
+};
+
+const testFactory = defineOpContext({
+  logSchema: defineLogSchema({
+    userId: S.category(),
+  }),
+  ctx: testCtxDefaults,
+}); // Create a tracer for testing with proper type
+const { trace: testTrace } = new TestTracer(testFactory, { ...createTestTracerOptions() });
+
+// =============================================================================
+// Type Enforcement Tests
+// =============================================================================
+
+describe('Tracer.trace Type Enforcement', () => {
+  it('should accept all required properties', async () => {
+    // This should compile without errors
+    const result = await testTrace(
+      'test-span',
+      {
+        env: { apiTimeout: 5000, region: 'us-east-1' },
+        requestId: 'req-123',
+        // userId is optional, can be omitted
+      },
+      (ctx) => {
+        expect(ctx).toBeDefined();
+        if (ctx.env === null) {
+          throw new Error('env should be populated from trace overrides');
+        }
+        expect(ctx.env.region).toBe('us-east-1');
+        expect(ctx.requestId).toBe('req-123');
+        return 'done';
+      },
+    );
+
+    expect(result).toBe('done');
+  });
+
+  it('should accept optional properties', async () => {
+    // This should compile without errors
+    const result = await testTrace(
+      'test-span',
+      {
+        env: { apiTimeout: 5000, region: 'us-east-1' },
+        requestId: 'req-123',
+        userId: 'user-456', // Optional property provided
+      },
+      (ctx) => {
+        expect(ctx).toBeDefined();
+        expect(ctx.userId).toBe('user-456');
+        return 'done';
+      },
+    );
+
+    expect(result).toBe('done');
+  });
+
+  // Note: Type-level tests for missing properties would require @ts-expect-error
+  // but the exact error message depends on TypeScript version.
+  // The important thing is that the API enforces required properties at the type level.
+  it('should require env and requestId (compile-time check)', async () => {
+    // This test documents that missing required properties cause compile errors
+    // We test by providing all required properties and verifying runtime behavior
+    const result = await testTrace(
+      'test-span',
+      {
+        env: { apiTimeout: 5000, region: 'us-east-1' },
+        requestId: 'req-123',
+      },
+      (ctx) => {
+        expect(ctx.env).toEqual({ apiTimeout: 5000, region: 'us-east-1' });
+        expect(ctx.requestId).toBe('req-123');
+        expect(ctx.userId).toBeUndefined();
+        return 'done';
+      },
+    );
+
+    expect(result).toBe('done');
+  });
+});
+
+// =============================================================================
+// Extra Type Flow Tests
+// =============================================================================
+
+describe('Context Type Flow Through Factory', () => {
+  it('should preserve ctx type through defineOpContext', async () => {
+    const defaults: { required: string | null; optional: number | undefined } = {
+      required: null,
+      optional: undefined,
+    };
+
+    const factory = defineOpContext({
+      logSchema: defineLogSchema({}),
+      ctx: defaults,
+    });
+
+    const { trace } = new TestTracer(factory, { ...createTestTracerOptions() });
+
+    // Type should be preserved - required is required, optional is optional
+    const result = await trace(
+      'test-span',
+      {
+        required: 'value',
+        // optional can be omitted
+      },
+      (ctx) => {
+        expect(ctx.required).toBe('value');
+        return 'done';
+      },
+    );
+
+    expect(result).toBe('done');
+  });
+
+  it('should work without ctx property', async () => {
+    // When ctx is not provided, no user context is available
+    const factory = defineOpContext({
+      logSchema: defineLogSchema({}),
+    });
+
+    const { trace } = new TestTracer(factory, { ...createTestTracerOptions() });
+
+    // Should accept empty options or no options
+    const result = await trace('test-span', (ctx) => {
+      expect(ctx).toBeDefined();
+      return 'done';
+    });
+
+    expect(result).toBe('done');
+  });
+});
+
+// =============================================================================
+// Reserved Keys Enforcement Tests
+// =============================================================================
+
+describe('Reserved Keys Enforcement', () => {
+  // Reserved context props are: buffer, tag, log, scope, setScope, ok, err, span, ff, deps
+
+  it('should throw at runtime for buffer reserved key', () => {
+    const invalidCtx: Record<string, unknown> = {
+      buffer: 'should-fail',
+    };
+    expect(() =>
+      defineOpContext({
+        logSchema: defineLogSchema({}),
+        ctx: invalidCtx,
+      }),
+    ).toThrow(/reserved/i);
+  });
+
+  it('should throw at runtime for span reserved key', () => {
+    const invalidCtx: Record<string, unknown> = {
+      span: () => {},
+    };
+    expect(() =>
+      defineOpContext({
+        logSchema: defineLogSchema({}),
+        ctx: invalidCtx,
+      }),
+    ).toThrow(/reserved/i);
+  });
+
+  it('should throw at runtime for ff reserved key', () => {
+    const invalidCtx: Record<string, unknown> = {
+      ff: {},
+    };
+    expect(() =>
+      defineOpContext({
+        logSchema: defineLogSchema({}),
+        ctx: invalidCtx,
+      }),
+    ).toThrow(/reserved/i);
+  });
+
+  it('should throw at runtime for tag reserved key', () => {
+    const invalidCtx: Record<string, unknown> = {
+      tag: {},
+    };
+    expect(() =>
+      defineOpContext({
+        logSchema: defineLogSchema({}),
+        ctx: invalidCtx,
+      }),
+    ).toThrow(/reserved/i);
+  });
+
+  it('should throw at runtime for log reserved key', () => {
+    const invalidCtx: Record<string, unknown> = {
+      log: {},
+    };
+    expect(() =>
+      defineOpContext({
+        logSchema: defineLogSchema({}),
+        ctx: invalidCtx,
+      }),
+    ).toThrow(/reserved/i);
+  });
+
+  it('should throw at runtime for ok reserved key', () => {
+    const invalidCtx: Record<string, unknown> = {
+      ok: () => {},
+    };
+    expect(() =>
+      defineOpContext({
+        logSchema: defineLogSchema({}),
+        ctx: invalidCtx,
+      }),
+    ).toThrow(/reserved/i);
+  });
+
+  it('should throw at runtime for err reserved key', () => {
+    const invalidCtx: Record<string, unknown> = {
+      err: () => {},
+    };
+    expect(() =>
+      defineOpContext({
+        logSchema: defineLogSchema({}),
+        ctx: invalidCtx,
+      }),
+    ).toThrow(/reserved/i);
+  });
+
+  it('should throw for underscore-prefixed properties', () => {
+    // Properties starting with _ are reserved for internal use
+    const invalidCtx: Record<string, unknown> = {
+      _internal: 'should-fail',
+    };
+    expect(() =>
+      defineOpContext({
+        logSchema: defineLogSchema({}),
+        ctx: invalidCtx,
+      }),
+    ).toThrow(/reserved/i);
+  });
+});

package/src/lib/__tests__/tracer.test.ts

@@ -0,0 +1,211 @@
+/**
+ * Tracer tests
+ *
+ * Tests for the Tracer class - the entry point for creating traces.
+ */
+
+import { describe, expect, it } from 'bun:test';
+// Must import test-helpers first to initialize timestamp implementation
+import './test-helpers.js';
+import { convertSpanTreeToArrowTable } from '../convertToArrow.js';
+import { defineOpContext } from '../defineOpContext.js';
+import { S } from '../schema/builder.js';
+import { defineLogSchema } from '../schema/defineLogSchema.js';
+import { createTraceId } from '../traceId.js';
+import { TestTracer } from '../tracers/TestTracer.js';
+import { createTestTracerOptions } from './test-helpers.js';
+
+// Test schema
+const testSchema = defineLogSchema({
+  userId: S.category(),
+  requestId: S.category(),
+  method: S.enum(['GET', 'POST', 'PUT', 'DELETE']),
+});
+
+// Test environment type
+interface TestEnv {
+  API_KEY: string;
+}
+
+const requiredEnvCtx: { env: TestEnv | null } = {
+  env: null,
+};
+
+const requiredRequestAndEnvCtx: { requestId: string | null; env: TestEnv | null } = {
+  requestId: null,
+  env: null,
+};
+
+const envAndConfigCtx: { env: TestEnv | null; config: { timeout: number } } = {
+  env: null,
+  config: { timeout: 5000 },
+};
+
+describe('Tracer', () => {
+  describe('basic functionality', () => {
+    it('should create a trace and return the body result', async () => {
+      const factory = defineOpContext({
+        logSchema: testSchema,
+        ctx: requiredEnvCtx,
+      });
+
+      const tracer = new TestTracer(factory, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const result = await trace('test-trace', { env: { API_KEY: 'test' } }, async (ctx) => {
+        ctx.tag.userId('user-123');
+        ctx.tag.method('GET');
+        return { success: true, data: 'hello' };
+      });
+
+      expect(result).toEqual({ success: true, data: 'hello' });
+      expect(tracer.rootBuffers.length).toBe(1);
+    });
+
+    it('should collect multiple traces in rootBuffers', async () => {
+      const factory = defineOpContext({
+        logSchema: testSchema,
+      });
+
+      const tracer = new TestTracer(factory, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      await trace('trace-1', async (ctx) => {
+        ctx.tag.userId('user-1');
+        return 'result-1';
+      });
+
+      await trace('trace-2', async (ctx) => {
+        ctx.tag.userId('user-2');
+        return 'result-2';
+      });
+
+      expect(tracer.rootBuffers.length).toBe(2);
+
+      // Convert each buffer to Arrow table to verify data
+      const table1 = convertSpanTreeToArrowTable(tracer.rootBuffers[0]);
+      const table2 = convertSpanTreeToArrowTable(tracer.rootBuffers[1]);
+
+      expect(table1.numRows).toBeGreaterThan(0);
+      expect(table2.numRows).toBeGreaterThan(0);
+    });
+
+    it('should handle errors and re-throw', async () => {
+      const factory = defineOpContext({
+        logSchema: testSchema,
+      });
+
+      const tracer = new TestTracer(factory, { ...createTestTracerOptions() });
+      const { trace } = tracer;
+
+      const error = new Error('test error');
+
+      await expect(
+        trace('error-trace', async () => {
+          throw error;
+        }),
+      ).rejects.toThrow('test error');
+
+      // Buffer should still be registered for flushing
+      expect(tracer.rootBuffers.length).toBe(1);
+    });
+
+    it('should accept optional trace ID', async () => {
+      const factory = defineOpContext({
+        logSchema: testSchema,
+      });
+
+      const { trace } = new TestTracer(factory, { ...createTestTracerOptions() });
+
+      const customTraceId = createTraceId('custom-trace-id-12345');
+
+      await trace('trace-with-id', { trace_id: customTraceId }, async (ctx) => {
+        // Access the trace ID from buffer
+        expect(ctx.buffer.trace_id).toBe(customTraceId);
+        return 'done';
+      });
+    });
+
+    it('should accept trace_id combined with userCtx overrides', async () => {
+      const factory = defineOpContext({
+        logSchema: testSchema,
+        ctx: requiredRequestAndEnvCtx,
+      });
+
+      const { trace } = new TestTracer(factory, { ...createTestTracerOptions() });
+      const customTraceId = createTraceId('combined-override-test');
+
+      await trace(
+        'combined-overrides',
+        { trace_id: customTraceId, requestId: 'req-123', env: { API_KEY: 'test' } },
+        async (ctx) => {
+          // Both trace_id and userCtx properties should be available
+          if (ctx.env === null) {
+            throw new Error('env should be provided in trace overrides');
+          }
+          expect(ctx.buffer.trace_id).toBe(customTraceId);
+          expect(ctx.requestId).toBe('req-123');
+          expect(ctx.env.API_KEY).toBe('test');
+          return 'done';
+        },
+      );
+    });
+
+    it('should merge ctx defaults with overrides', async () => {
+      const factory = defineOpContext({
+        logSchema: testSchema,
+        ctx: envAndConfigCtx,
+      });
+
+      const { trace } = new TestTracer(factory, { ...createTestTracerOptions() });
+
+      await trace('ctx-test', { env: { API_KEY: 'secret' } }, async (ctx) => {
+        if (ctx.env === null) {
+          throw new Error('env should be provided in trace overrides');
+        }
+        // env should be from overrides
+        expect(ctx.env.API_KEY).toBe('secret');
+        // config should use default
+        expect(ctx.config.timeout).toBe(5000);
+        return 'done';
+      });
+
+      // Can override config too
+      await trace('ctx-test-2', { env: { API_KEY: 'key2' }, config: { timeout: 10000 } }, async (ctx) => {
+        expect(ctx.config.timeout).toBe(10000);
+        return 'done';
+      });
+    });
+  });
+
+  describe('overload signatures', () => {
+    it('should work without overrides (name, fn)', async () => {
+      const factory = defineOpContext({
+        logSchema: testSchema,
+      });
+
+      const { trace } = new TestTracer(factory, { ...createTestTracerOptions() });
+
+      const result = await trace('simple', async () => {
+        return 42;
+      });
+
+      expect(result).toBe(42);
+    });
+
+    it('should work with overrides (name, overrides, fn)', async () => {
+      const factory = defineOpContext({
+        logSchema: testSchema,
+        ctx: { value: 0 },
+      });
+
+      const { trace } = new TestTracer(factory, { ...createTestTracerOptions() });
+
+      const result = await trace('with-overrides', { value: 100 }, async (ctx) => {
+        return ctx.value;
+      });
+
+      expect(result).toBe(100);
+    });
+  });
+});

package/src/lib/__tests__/type-narrowing.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Tests for TypeScript type narrowing with FluentResult
+ * Ensures that result.success properly narrows types
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { defineOpContext } from '../defineOpContext.js';
+import { defineCodeError } from '../result.js';
+import { S } from '../schema/builder.js';
+import { defineLogSchema } from '../schema/defineLogSchema.js';
+import { TestTracer } from '../tracers/TestTracer.js';
+import { createTestTracerOptions } from './test-helpers.js';
+
+// Error code factories for tests
+const TEST_ERROR = defineCodeError('TEST_ERROR')<{ field: string; reason: string }>();
+const VALIDATION_ERROR = defineCodeError('VALIDATION_ERROR')<{ message: string }>();
+
+const testSchema = defineLogSchema({
+  userId: S.category(),
+  customField: S.category(),
+});
+
+// Create op context factory
+const opContext = defineOpContext({
+  logSchema: testSchema,
+  ctx: {
+    requestId: undefined as string | undefined,
+  },
+});
+
+const { defineOp } = opContext;
+
+// Create a properly typed tracer - new API passes opContext directly
+function createTestTracer() {
+  return new TestTracer(opContext, { ...createTestTracerOptions() });
+}
+
+describe('Type Narrowing with FluentResult', () => {
+  it('should properly narrow success result type', async () => {
+    const { trace } = createTestTracer();
+
+    const testOp = defineOp('testOp', async (ctx) => {
+      const result = ctx.ok({ id: 123, name: 'test' });
+
+      // Type narrowing should work with FluentResult
+      if (result.success) {
+        // result.value should be accessible and typed correctly
+        const value = result.value;
+        expect(value.id).toBe(123);
+        expect(value.name).toBe('test');
+        return result;
+      }
+
+      return ctx.ok(null);
+    });
+
+    const output = await trace('testOp', testOp);
+    expect(output.success).toBe(true);
+    if (output.success) {
+      expect(output.value).toEqual({ id: 123, name: 'test' });
+    }
+  });
+
+  it('should properly narrow error result type', async () => {
+    const { trace } = createTestTracer();
+
+    const testOp = defineOp('testOp', async (ctx) => {
+      const result = ctx.err(TEST_ERROR({ field: 'email', reason: 'invalid' }));
+
+      // Type narrowing should work with FluentResult
+      if (!result.success) {
+        // result.error should be accessible and typed correctly
+        const error = result.error;
+        expect(error.code).toBe('TEST_ERROR');
+        expect(error.field).toBe('email');
+        expect(error.reason).toBe('invalid');
+        return ctx.ok(error.code);
+      }
+
+      return ctx.ok(null);
+    });
+
+    const output = await trace('testOp', testOp);
+    expect(output.success).toBe(true);
+    if (output.success) {
+      expect(output.value).toBe('TEST_ERROR');
+    }
+  });
+
+  it('should support chaining before type check', async () => {
+    const { trace } = createTestTracer();
+
+    const testOp = defineOp('testOp', async (ctx) => {
+      const result = ctx.ok({ id: 456 }).with({ userId: 'user1' }).message('Success');
+
+      // Type narrowing should still work after chaining
+      if (result.success) {
+        expect(result.value.id).toBe(456);
+        return ctx.ok(result.value.id);
+      }
+
+      return ctx.ok(0);
+    });
+
+    const output = await trace('testOp', testOp);
+    expect(output.success).toBe(true);
+    if (output.success) {
+      expect(output.value).toBe(456);
+    }
+  });
+
+  it('should handle error result with chaining', async () => {
+    const { trace } = createTestTracer();
+
+    const testOp = defineOp('testOp', async (ctx) => {
+      const result = ctx
+        .err(VALIDATION_ERROR({ message: 'Invalid input' }))
+        .with({ userId: 'user1' })
+        .message('Validation failed');
+
+      // Type narrowing should work after chaining
+      if (!result.success) {
+        expect(result.error.code).toBe('VALIDATION_ERROR');
+        expect(result.error.message).toBe('Invalid input');
+        return ctx.ok(result.error.code);
+      }
+
+      return ctx.ok('OK');
+    });
+
+    const output = await trace('testOp', testOp);
+    expect(output.success).toBe(true);
+    if (output.success) {
+      expect(output.value).toBe('VALIDATION_ERROR');
+    }
+  });
+});

package/src/lib/archive/chunkCompaction.ts

@@ -0,0 +1,44 @@
+import type { TraceChunkEnvelope } from './chunkEnvelope.js';
+
+export interface CompactionWindow {
+  readonly started_at_ms: number;
+  readonly ended_at_ms: number;
+}
+
+export interface CompactedChunkSet {
+  readonly compaction_id: string;
+  readonly source_set_hash: string;
+  readonly source_chunk_ids: readonly string[];
+  readonly source_chunk_count: number;
+  readonly total_rows: number;
+  readonly window: CompactionWindow;
+}
+
+export function compactTraceChunks(chunks: readonly TraceChunkEnvelope[], window: CompactionWindow): CompactedChunkSet {
+  const sourceChunkIds = [...new Set(chunks.map((chunk) => chunk.chunk_id))].sort();
+  const totalRows = chunks.reduce((sum, chunk) => sum + chunk.row_count, 0);
+  const source_set_hash = hashDeterministic(sourceChunkIds.join('|'));
+  const compaction_id = `compact_${hashDeterministic(`${source_set_hash}:${window.started_at_ms}:${window.ended_at_ms}`)}`;
+
+  return {
+    compaction_id,
+    source_set_hash,
+    source_chunk_ids: sourceChunkIds,
+    source_chunk_count: sourceChunkIds.length,
+    total_rows: totalRows,
+    window,
+  };
+}
+
+function hashDeterministic(input: string): string {
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  const mod = 0xffffffffffffffffn;
+
+  for (let i = 0; i < input.length; i++) {
+    hash ^= BigInt(input.charCodeAt(i));
+    hash = (hash * prime) & mod;
+  }
+
+  return hash.toString(16).padStart(16, '0');
+}