@smoothbricks/lmao 0.1.0

package/src/lib/traceRoot.node.ts

@@ -0,0 +1,170 @@
+/// <reference types="node" />
+
+/**
+ * TraceRoot - Node.js implementation.
+ *
+ * Uses process.hrtime.bigint() for true nanosecond precision and writes directly
+ * to SpanBuffer state from JavaScript.
+ *
+ * @module traceRoot.node
+ */
+
+import { Nanoseconds } from '@smoothbricks/arrow-builder';
+import { ENTRY_TYPE_SPAN_EXCEPTION, ENTRY_TYPE_SPAN_START } from './schema/systemSchema.js';
+import { createTraceId, type TraceId } from './traceId.js';
+import {
+  type ITraceRoot,
+  TRACE_ROOT_ANCHOR_EPOCH_OFFSET,
+  TRACE_ROOT_ANCHOR_PERF_OFFSET,
+  TRACE_ROOT_TRACE_ID_LEN_OFFSET,
+  TRACE_ROOT_TRACE_ID_OFFSET,
+  type TracerLifecycleHooks,
+} from './traceRoot.js';
+import type { AnySpanBuffer } from './types.js';
+
+/** Shared TextEncoder for trace_id encoding (stateless, reusable) */
+const textEncoder = new TextEncoder();
+
+/** Shared TextDecoder for trace_id decoding (stateless, reusable) */
+const textDecoder = new TextDecoder();
+
+/**
+ * TraceRoot - Node.js implementation.
+ *
+ * Stores anchor data in _system ArrayBuffer and writes timestamps directly from JS.
+ */
+export class TraceRoot implements ITraceRoot {
+  /**
+   * Raw backing buffer containing anchor timestamps and trace_id.
+   */
+  readonly _system: ArrayBuffer;
+
+  /**
+   * Tracer reference for lifecycle hooks and event callbacks.
+   */
+  readonly tracer: TracerLifecycleHooks;
+
+  /**
+   * Cached TypedArray views for fast JS access.
+   */
+  private readonly _epochView: BigInt64Array;
+  private readonly _perfView: Float64Array;
+
+  /**
+   * Cached anchor hrtime as BigInt for JS timestamp fallback.
+   * Only used if NAPI addon is not available.
+   */
+  private readonly _anchorHrtimeBigInt: bigint;
+
+  constructor(
+    trace_id: TraceId,
+    anchorEpochNanos: bigint,
+    anchorPerfNow: number,
+    anchorHrtimeBigInt: bigint,
+    tracer: TracerLifecycleHooks,
+  ) {
+    // Allocate buffer: 17 bytes header + trace_id length
+    // trace_id is validated to be ASCII (1 byte per char) so length === byte length
+    this._system = new ArrayBuffer(TRACE_ROOT_TRACE_ID_OFFSET + trace_id.length);
+    this.tracer = tracer;
+
+    // Create cached views (one-time allocation)
+    this._epochView = new BigInt64Array(this._system, TRACE_ROOT_ANCHOR_EPOCH_OFFSET, 1);
+    this._perfView = new Float64Array(this._system, TRACE_ROOT_ANCHOR_PERF_OFFSET, 1);
+
+    // Write anchor data directly
+    this._epochView[0] = anchorEpochNanos;
+    this._perfView[0] = anchorPerfNow;
+
+    // Keep exact monotonic anchor for JS fallback (avoid Number precision loss after ~104 days uptime)
+    this._anchorHrtimeBigInt = anchorHrtimeBigInt;
+
+    // Encode trace_id directly into buffer (no intermediate allocation)
+    const u8View = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET);
+    const traceIdDest = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, trace_id.length);
+    const { written } = textEncoder.encodeInto(trace_id, traceIdDest);
+    u8View[0] = written;
+  }
+
+  /**
+   * Epoch time in nanoseconds when trace was created.
+   */
+  get anchorEpochNanos(): bigint {
+    return this._epochView[0];
+  }
+
+  /**
+   * High-resolution timer anchor when trace was created.
+   */
+  get anchorPerfNow(): number {
+    return this._perfView[0];
+  }
+
+  /**
+   * Trace ID for this trace.
+   */
+  get trace_id(): TraceId {
+    const len = new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_LEN_OFFSET, 1)[0];
+    return createTraceId(textDecoder.decode(new Uint8Array(this._system, TRACE_ROOT_TRACE_ID_OFFSET, len)));
+  }
+
+  /**
+   * Get current timestamp in nanoseconds since Unix epoch.
+   * Uses process.hrtime.bigint() for true nanosecond precision.
+   */
+  getTimestampNanos(): Nanoseconds {
+    const currentHrtime = process.hrtime.bigint();
+    const elapsedNanos = currentHrtime - this._anchorHrtimeBigInt;
+    return Nanoseconds.unsafe(this._epochView[0] + elapsedNanos);
+  }
+
+  /**
+   * Write span-start entry to buffer at row 0.
+   *
+   */
+  writeSpanStart(buffer: AnySpanBuffer, spanName: string): void {
+    buffer.timestamp[0] = this.getTimestampNanos();
+    buffer.entry_type[0] = ENTRY_TYPE_SPAN_START;
+    buffer.message(0, spanName);
+
+    // Pre-initialize row 1 as span-exception
+    buffer.entry_type[1] = ENTRY_TYPE_SPAN_EXCEPTION;
+    buffer.timestamp[1] = 0n;
+
+    buffer._writeIndex = 2;
+  }
+
+  /**
+   * Write span-end entry to buffer at row 1.
+   * Writes both timestamp and entry_type.
+   *
+   */
+  writeSpanEnd(buffer: AnySpanBuffer, entryType: number): void {
+    buffer.timestamp[1] = this.getTimestampNanos();
+    buffer.entry_type[1] = entryType;
+  }
+
+  /**
+   * Write log entry: bump writeIndex, write timestamp + entry_type, return idx.
+   * SpanLogger uses returned idx for string column writes.
+   */
+  writeLogEntry(buffer: AnySpanBuffer, entryType: number): number {
+    const idx = buffer._writeIndex;
+    buffer.timestamp[idx] = this.getTimestampNanos();
+    buffer.entry_type[idx] = entryType;
+    buffer._writeIndex = idx + 1;
+    return idx;
+  }
+}
+
+/**
+ * Factory function for creating Node.js TraceRoot instances.
+ * Pass this to Tracer constructor for Node.js environments.
+ */
+export function createTraceRoot(trace_id: string, tracer: TracerLifecycleHooks): TraceRoot {
+  const anchorEpochNanos = BigInt(Date.now()) * 1_000_000n;
+  const anchorHrtimeBigInt = process.hrtime.bigint();
+  // Store as number for NAPI to read as f64
+  const anchorPerfNow = Number(anchorHrtimeBigInt);
+  return new TraceRoot(createTraceId(trace_id), anchorEpochNanos, anchorPerfNow, anchorHrtimeBigInt, tracer);
+}

package/src/lib/traceRoot.ts

@@ -0,0 +1,154 @@
+/**
+ * TraceRoot - Platform-agnostic interface for trace anchoring and timestamp writes.
+ *
+ * TraceRoot manages:
+ * - Trace ID storage
+ * - Timestamp anchoring (epoch + high-res timer reference)
+ * - Writing span-start/span-end to SpanBuffer's _system columns
+ *
+ * Platform-specific implementations:
+ * - TraceRoot.es.ts: Browser - uses performance.now() for timing
+ * - TraceRoot.node.ts: Node.js - delegates to NAPI addon for optimized writes
+ *
+ * @module traceRoot
+ */
+
+import type { Nanoseconds } from '@smoothbricks/arrow-builder';
+import type { AnySpanBuffer } from './types.js';
+
+export type { SpanIdentity, TraceId } from './traceId.js';
+// Re-export TraceId types from traceId.ts
+export { createTraceId, extractSpanIdentity, generateTraceId, isValidTraceId, MAX_TRACE_ID_LENGTH } from './traceId.js';
+
+/**
+ * Tracer lifecycle hooks interface.
+ * Extracted to avoid circular dependency - Tracer implements this.
+ */
+export interface TracerLifecycleHooks {
+  onTraceStart(buffer: unknown): void;
+  onTraceEnd(buffer: unknown): void;
+  onSpanStart(buffer: unknown): void;
+  onSpanEnd(buffer: unknown): void;
+  onStatsWillResetFor(buffer: unknown): void;
+
+  /**
+   * Buffer strategy for creating child and overflow buffers.
+   * SpanContext uses this to create child spans with the correct strategy (JS or WASM).
+   * Note: Caller must call writeSpanStart() after createChildSpanBuffer() to set span name.
+   */
+  readonly bufferStrategy: {
+    createChildSpanBuffer(
+      parentBuffer: AnySpanBuffer,
+      callsiteMetadata: unknown,
+      opMetadata: unknown,
+      capacity?: number,
+      schema?: unknown,
+    ): AnySpanBuffer;
+    createOverflowBuffer(buffer: AnySpanBuffer): AnySpanBuffer;
+  };
+}
+
+/**
+ * TraceRoot._system memory layout (little-endian):
+ *
+ * Offset  Size   Field
+ * 0       8      anchorEpochNanos (i64) - epoch time in nanoseconds
+ * 8       8      anchorPerfNow (f64) - high-res timer anchor
+ * 16      1      trace_id_len (u8) - length of trace_id UTF-8 bytes
+ * 17      N      trace_id (UTF-8 bytes)
+ *
+ * Total: 17 + trace_id.length bytes
+ *
+ * This layout enables NAPI/WASM to read anchors directly without BigInt extraction.
+ */
+export const TRACE_ROOT_ANCHOR_EPOCH_OFFSET = 0;
+export const TRACE_ROOT_ANCHOR_PERF_OFFSET = 8;
+export const TRACE_ROOT_TRACE_ID_LEN_OFFSET = 16;
+export const TRACE_ROOT_TRACE_ID_OFFSET = 17;
+
+/**
+ * TraceRoot interface - implemented by platform-specific classes.
+ *
+ * Each implementation handles timestamp calculation and span writes differently:
+ * - Browser: Pure JS with performance.now()
+ * - Node.js: NAPI addon with mach_absolute_time() / clock_gettime()
+ */
+/**
+ * Factory function type for creating platform-specific TraceRoot instances.
+ * Passed to Tracer constructor to enable tree-shaking of unused platform code.
+ *
+ * The factory creates anchor timestamps internally using platform-specific APIs.
+ */
+export type TraceRootFactory = (trace_id: string, tracer: TracerLifecycleHooks) => ITraceRoot;
+
+export interface ITraceRoot {
+  /**
+   * Raw backing buffer containing anchor timestamps and trace_id.
+   * NAPI/WASM can read this directly without BigInt extraction.
+   */
+  readonly _system: ArrayBuffer;
+
+  /**
+   * Tracer reference for lifecycle hooks and event callbacks.
+   */
+  readonly tracer: TracerLifecycleHooks;
+
+  /**
+   * Trace ID for this trace.
+   */
+  readonly trace_id: string;
+
+  /**
+   * Epoch time in nanoseconds when trace was created.
+   * Used by SpanLogger for log entry timestamps.
+   */
+  readonly anchorEpochNanos: bigint;
+
+  /**
+   * High-resolution timer anchor when trace was created.
+   * Browser: performance.now() value (number)
+   * Node.js: stored as number for NAPI compatibility, but represents hrtime
+   */
+  readonly anchorPerfNow: number;
+
+  /**
+   * Get current timestamp in nanoseconds since Unix epoch.
+   * Platform-specific implementation.
+   */
+  getTimestampNanos(): Nanoseconds;
+
+  /**
+   * Write span-start entry to buffer at row 0.
+   *
+   * Writes:
+   * - timestamp[0] = current time
+   * - entry_type[0] = SPAN_START
+   * - entry_type[1] = SPAN_EXCEPTION (pre-initialized for crash safety)
+   * - timestamp[1] = 0 (will be set on completion)
+   * - message[0] = spanName
+   * - _writeIndex = 2
+   *
+   * @param buffer - SpanBuffer to write to
+   * @param spanName - Name for this span
+   */
+  writeSpanStart(buffer: AnySpanBuffer, spanName: string): void;
+
+  /**
+   * Write span-end entry to buffer at row 1.
+   * Writes both timestamp and entry_type.
+   *
+   * @param buffer - SpanBuffer to write to
+   * @param entryType - Entry type (SPAN_OK, SPAN_ERR, or SPAN_EXCEPTION)
+   */
+  writeSpanEnd(buffer: AnySpanBuffer, entryType: number): void;
+
+  /**
+   * Write log entry: bump writeIndex, write timestamp + entry_type, return idx.
+   * SpanLogger uses returned idx for string column writes.
+   *
+   * @param buffer - SpanBuffer to write to
+   * @param entryType - Entry type (INFO, DEBUG, WARN, ERROR, TRACE, FF_ACCESS, FF_USAGE)
+   * @returns The row index where entry was written
+   */
+  writeLogEntry(buffer: AnySpanBuffer, entryType: number): number;
+}

package/src/lib/traceRoot.universal.ts

@@ -0,0 +1,22 @@
+/// <reference types="node" />
+
+/**
+ * TraceRoot - Universal implementation with runtime platform detection.
+ *
+ * Selects between Node.js (nanosecond hrtime) and ES (performance.now()) based
+ * on whether process.hrtime.bigint is available at runtime.
+ *
+ * Both modules are safe to import — platform-specific calls (process.hrtime.bigint(),
+ * NAPI addon) happen inside the factory function, not at module scope.
+ *
+ * @module traceRoot.universal
+ */
+
+import { createTraceRoot as esFactory } from './traceRoot.es.js';
+import type { TraceRootFactory } from './traceRoot.js';
+import { createTraceRoot as nodeFactory } from './traceRoot.node.js';
+
+// Node/Bun → nanosecond precision via hrtime.bigint()
+// CF Workers/browsers → performance.now() microsecond precision
+export const createTraceRoot: TraceRootFactory =
+  typeof process !== 'undefined' && typeof process.hrtime?.bigint === 'function' ? nodeFactory : esFactory;