@smoothbricks/lmao 0.1.0

package/src/lib/tracers/ArrayQueueTracer.ts

@@ -0,0 +1,76 @@
+import type { OpContextBinding } from '../opContext/types.js';
+import { Tracer } from '../tracer.js';
+import type { SpanBuffer } from '../types.js';
+
+/**
+ * Tracer that batches completed root traces in an in-memory queue.
+ *
+ * Use `drain()` to consume all queued buffers and clear the queue.
+ * Designed for production scenarios where traces should be batched
+ * before sending to a backend.
+ *
+ * @example
+ * ```typescript
+ * import { createTraceRoot } from '@smoothbricks/lmao/node';
+ * import { JsBufferStrategy } from '@smoothbricks/lmao';
+ *
+ * const ctx = defineOpContext({ logSchema });
+ * const tracer = new ArrayQueueTracer(ctx, {
+ *   bufferStrategy: new JsBufferStrategy(),
+ *   createTraceRoot,
+ * });
+ * const { trace } = tracer;
+ *
+ * // Process requests, traces accumulate
+ * await trace('request-1', handleRequest, req1);
+ * await trace('request-2', handleRequest, req2);
+ *
+ * // Periodically drain and process
+ * const batch = tracer.drain();
+ * for (const buf of batch) {
+ *   const table = await tracer.bufferStrategy.toArrowTable(buf);
+ *   await sendToBackend(table);
+ *   tracer.bufferStrategy.releaseBuffer(buf);
+ * }
+ * ```
+ */
+export class ArrayQueueTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
+  /**
+   * Queue of completed root trace buffers.
+   * Use `drain()` to consume and clear.
+   * Public for test inspection.
+   */
+  readonly queue: SpanBuffer<B['logBinding']['logSchema']>[] = [];
+
+  onTraceStart(_rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    this.queue.push(rootBuffer);
+  }
+
+  onSpanStart(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  onSpanEnd(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  onStatsWillResetFor(_buffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op - override in subclass to capture stats
+  }
+
+  /**
+   * Consume all queued buffers and clear the queue.
+   * Returns an independent copy of the queue contents.
+   *
+   * @returns Array of root buffers (with child spans in _children tree)
+   */
+  drain(): SpanBuffer<B['logBinding']['logSchema']>[] {
+    const buffers = [...this.queue];
+    this.queue.length = 0;
+    return buffers;
+  }
+}

package/src/lib/tracers/CompositeTracer.ts

@@ -0,0 +1,76 @@
+import type { OpContextBinding } from '../opContext/types.js';
+import { Tracer, type TracerOptions } from '../tracer.js';
+import type { SpanBuffer } from '../types.js';
+
+type MaybeClose = { close?: () => void | Promise<void> };
+
+function hasClose(value: unknown): value is MaybeClose {
+  return typeof value === 'object' && value !== null && typeof Reflect.get(value, 'close') === 'function';
+}
+
+export interface CompositeTracerOptions<B extends OpContextBinding = OpContextBinding>
+  extends TracerOptions<B['logBinding']['logSchema']> {
+  delegates: Tracer<B>[];
+}
+
+/**
+ * Composite tracer that fans lifecycle hooks out to delegate tracers.
+ *
+ * Useful when you want multiple outputs from a single trace run,
+ * for example Stdio + SQLite.
+ */
+export class CompositeTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
+  private readonly delegates: Tracer<B>[];
+
+  constructor(binding: B, options: CompositeTracerOptions<B>) {
+    super(binding, options);
+    this.delegates = options.delegates;
+  }
+
+  onTraceStart(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    for (const tracer of this.delegates) {
+      tracer.onTraceStart(rootBuffer);
+    }
+  }
+
+  onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    for (const tracer of this.delegates) {
+      tracer.onTraceEnd(rootBuffer);
+    }
+  }
+
+  onSpanStart(childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    for (const tracer of this.delegates) {
+      tracer.onSpanStart(childBuffer);
+    }
+  }
+
+  onSpanEnd(childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    for (const tracer of this.delegates) {
+      tracer.onSpanEnd(childBuffer);
+    }
+  }
+
+  onStatsWillResetFor(buffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    for (const tracer of this.delegates) {
+      tracer.onStatsWillResetFor(buffer);
+    }
+  }
+
+  override async flush(): Promise<void> {
+    for (const tracer of this.delegates) {
+      await tracer.flush();
+    }
+  }
+
+  async close(): Promise<void> {
+    for (const tracer of this.delegates) {
+      if (hasClose(tracer)) {
+        const { close } = tracer;
+        if (close) {
+          await close.call(tracer);
+        }
+      }
+    }
+  }
+}

package/src/lib/tracers/NoOpTracer.ts

@@ -0,0 +1,73 @@
+/**
+ * NoOpTracer - A tracer that executes ops but discards all trace data
+ *
+ * All lifecycle hooks are no-ops - traces execute normally but produce no output.
+ * Useful for:
+ * - Tests that don't need to inspect trace output
+ * - Disabling tracing in production without code changes
+ * - Baseline performance testing (measures op execution cost without tracing overhead)
+ *
+ * @example
+ * ```typescript
+ * import { createTraceRoot } from '@smoothbricks/lmao/node';
+ * import { JsBufferStrategy } from '@smoothbricks/lmao';
+ *
+ * const ctx = defineOpContext({ logSchema });
+ * const { trace } = new NoOpTracer(ctx, {
+ *   bufferStrategy: new JsBufferStrategy(),
+ *   createTraceRoot,
+ * });
+ *
+ * // Trace executes, result returned, no side effects
+ * const result = await trace('fetch', fetchOp);
+ * ```
+ */
+
+import type { OpContextBinding } from '../opContext/types.js';
+import { Tracer } from '../tracer.js';
+import type { SpanBuffer } from '../types.js';
+
+/**
+ * No-op tracer - executes ops normally but discards all trace data
+ *
+ * All lifecycle hooks are empty - no processing, no output.
+ * Useful for testing and measuring op execution cost without trace overhead.
+ *
+ * @typeParam B - OpContextBinding type
+ */
+export class NoOpTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
+  /**
+   * No-op hook for trace start.
+   */
+  onTraceStart(_rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  /**
+   * No-op hook for trace end.
+   */
+  onTraceEnd(_rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  /**
+   * No-op hook for span start.
+   */
+  onSpanStart(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  /**
+   * No-op hook for span end.
+   */
+  onSpanEnd(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  /**
+   * No-op hook for stats reset.
+   */
+  onStatsWillResetFor(_buffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+}

package/src/lib/tracers/SQLiteTracer.ts

@@ -0,0 +1,115 @@
+import type { OpContextBinding } from '../opContext/types.js';
+import { SQLiteAsyncTraceWriter } from '../sqlite/sqlite-async-writer.js';
+import type { AsyncSQLiteDatabase, SyncSQLiteDatabase } from '../sqlite/sqlite-db.js';
+import { SQLiteTraceWriter } from '../sqlite/sqlite-writer.js';
+import { Tracer, type TracerOptions } from '../tracer.js';
+import type { SpanBuffer } from '../types.js';
+
+export interface SQLiteTracerOptions<
+  T extends import('../schema/LogSchema.js').LogSchema = import('../schema/LogSchema.js').LogSchema,
+> extends TracerOptions<T> {
+  db: SyncSQLiteDatabase;
+}
+
+export interface SQLiteAsyncTracerOptions<
+  T extends import('../schema/LogSchema.js').LogSchema = import('../schema/LogSchema.js').LogSchema,
+> extends TracerOptions<T> {
+  db: AsyncSQLiteDatabase | Promise<AsyncSQLiteDatabase>;
+}
+
+/**
+ * Tracer that persists completed root traces to SQLite synchronously.
+ */
+export class SQLiteTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
+  private readonly writer: SQLiteTraceWriter;
+
+  constructor(binding: B, options: SQLiteTracerOptions<B['logBinding']['logSchema']>) {
+    super(binding, options);
+    this.writer = new SQLiteTraceWriter(options.db);
+  }
+
+  onTraceStart(_rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    this.writer.flush(rootBuffer);
+  }
+
+  onSpanStart(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  onSpanEnd(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  onStatsWillResetFor(_buffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  async close(): Promise<void> {
+    this.writer.close();
+  }
+}
+
+/**
+ * Tracer that persists completed root traces to SQLite asynchronously.
+ *
+ * onTraceEnd starts a background write pipeline; flush() awaits pipeline completion.
+ */
+export class SQLiteAsyncTracer<B extends OpContextBinding = OpContextBinding> extends Tracer<B> {
+  private readonly writerPromise: Promise<SQLiteAsyncTraceWriter>;
+  private pendingWrites: Promise<void> = Promise.resolve();
+  private pendingErrors: unknown[] = [];
+
+  constructor(binding: B, options: SQLiteAsyncTracerOptions<B['logBinding']['logSchema']>) {
+    super(binding, options);
+    this.writerPromise = Promise.resolve(options.db).then((db) => new SQLiteAsyncTraceWriter(db));
+  }
+
+  onTraceStart(_rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  onTraceEnd(rootBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    this.pendingWrites = this.pendingWrites.then(async () => {
+      try {
+        const writer = await this.writerPromise;
+        await writer.flush(rootBuffer);
+      } catch (error) {
+        this.pendingErrors.push(error);
+      }
+    });
+  }
+
+  onSpanStart(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  onSpanEnd(_childBuffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  onStatsWillResetFor(_buffer: SpanBuffer<B['logBinding']['logSchema']>): void {
+    // No-op
+  }
+
+  override async flush(): Promise<void> {
+    await this.pendingWrites;
+    if (this.pendingErrors.length > 0) {
+      const errors = this.pendingErrors;
+      this.pendingErrors = [];
+      if (errors.length === 1) {
+        throw errors[0];
+      }
+      throw new AggregateError(errors, `SQLiteAsyncTracer flush failed for ${errors.length} trace writes`);
+    }
+  }
+
+  async close(): Promise<void> {
+    await this.flush();
+    const writer = await this.writerPromise;
+    await writer.close();
+  }
+}