@smoothbricks/lmao 0.1.0

package/dist/lib/traceContext.d.ts

@@ -0,0 +1,116 @@
+/**
+ * TraceContext Types and Prototype System
+ *
+ * Per specs/lmao/01c_context_flow_and_op_wrappers.md and specs/lmao/01l_op_context_pattern.md:
+ * - TraceContext is created via module.traceContext() at request entry
+ * - Uses prototype-based inheritance for V8 hidden class optimization
+ * - Contains system properties (traceId, timestamps, threadId) + user Extra
+ */
+import type { OpContext } from './opContext/types.js';
+import type { Result } from './result.js';
+import type { FeatureFlagSchema } from './schema/defineFeatureFlags.js';
+import type { FlagEvaluator } from './schema/evaluator.js';
+import type { LogSchema } from './schema/types.js';
+import type { TraceId } from './traceId.js';
+/**
+ * Reserved keys that Extra cannot contain (compile-time enforcement)
+ *
+ * Per spec 01l lines 379-386
+ */
+export type ReservedTraceContextKeys = 'traceId' | 'anchorEpochMicros' | 'anchorPerfNow' | 'threadId' | 'ff' | 'span';
+/**
+ * Op type - traced operation
+ *
+ * Imported from op.ts to break circular dependency.
+ * The actual Op class is defined in op.ts.
+ */
+import type { Op } from './op.js';
+export type { Op } from './op.js';
+/**
+ * Function type for ctx.span() at the root level
+ *
+ * Per spec 01c lines 243-244 and experiment exp7-full-ctx.ts lines 253-259:
+ * Supports both with and without line number (transformer injects line number)
+ *
+ * The first argument (lineNumber) is injected by the transformer.
+ */
+export type RootSpanFn = {
+    <Ctx extends OpContext, Args extends unknown[], S, E>(line: number, name: string, op: Op<Ctx, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+    <Ctx extends OpContext, Args extends unknown[], S, E>(name: string, op: Op<Ctx, Args, S, E>, ...args: Args): Promise<Result<S, E>>;
+};
+/**
+ * TraceContext system properties - root context created via module.traceContext()
+ *
+ * Per spec 01c lines 206-216 and 01l lines 369-377:
+ * - System properties are auto-generated and cannot be overridden via Extra
+ *
+ * @typeParam FF - Feature flag schema type
+ * @typeParam T - LogSchema type (for typed evaluation context)
+ * @typeParam Env - Environment type
+ */
+export interface TraceContextSystem<FF extends FeatureFlagSchema, T extends LogSchema = LogSchema, Env extends Record<string, unknown> = Record<string, unknown>> {
+    readonly anchorEpochMicros: number;
+    readonly anchorPerfNow: number;
+    /** Root flag evaluator - use forContext(spanCtx) to get span-bound evaluator */
+    readonly ff: FlagEvaluator<OpContext<T, FF, Record<string, never>, Env>>;
+    readonly span: RootSpanFn;
+}
+/**
+ * TraceContext - system properties + user Extra
+ *
+ * Per spec 01c lines 215-216:
+ * ```typescript
+ * interface TraceContext<FF, Extra> { ... } & Extra;
+ * ```
+ *
+ * Extra properties are spread via intersection at usage site.
+ *
+ * @typeParam FF - Feature flag schema type
+ * @typeParam Extra - User-defined properties (e.g., requestId, userId, env)
+ */
+export type TraceContext<FF extends FeatureFlagSchema, Extra extends Record<string, unknown>> = TraceContextSystem<FF> & Extra;
+/**
+ * Internal symbol to mark contexts as prototype-based
+ * Used for type guards and instanceof-like checks
+ */
+export declare const TRACE_CONTEXT_MARKER: unique symbol;
+/**
+ * Base prototype interface for all trace contexts.
+ *
+ * Per specs/lmao/01c_context_flow_and_op_wrappers.md:
+ * - Methods are defined ONCE on a shared prototype
+ * - Object.create() is used for inheritance (no object spreads)
+ * - Properties are assigned directly for stable hidden classes
+ *
+ * This is used internally and should not be accessed directly.
+ */
+export interface TraceContextBase {
+    /** Marker for prototype chain detection */
+    readonly [TRACE_CONTEXT_MARKER]: true;
+    /** Trace ID for this context */
+    trace_id: TraceId | undefined;
+    /** Epoch microseconds when trace started */
+    anchorEpochMicros: number | undefined;
+    /** performance.now() when trace started */
+    anchorPerfNow: number | undefined;
+    /** Feature flag evaluator */
+    ff: unknown;
+    /** Root span function */
+    span: unknown;
+    /** Pre-computed Extra keys for V8 optimization (avoid Object.keys in hot path) */
+    _extraKeys?: string[];
+}
+/**
+ * The shared prototype object for TraceContext.
+ *
+ * Per V8 optimization guidelines:
+ * - Define methods ONCE on prototype, not per-instance
+ * - Use Object.create() for inheritance chains
+ * - Avoid object spreads which break hidden classes
+ */
+export declare const TraceContextProto: TraceContextBase;
+/**
+ * Type guard to check if a value is a TraceContext
+ */
+export declare function isTraceContext(value: unknown): value is TraceContext<FeatureFlagSchema, Record<string, unknown>>;
+//# sourceMappingURL=traceContext.d.ts.map

package/dist/lib/traceContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceContext.d.ts","sourceRoot":"","sources":["../../src/lib/traceContext.ts"],"names":[],"mappings":"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"}

package/dist/lib/traceContext.js

@@ -0,0 +1,37 @@
+// =============================================================================
+// Prototype System for V8 Hidden Class Optimization
+// =============================================================================
+/**
+ * Internal symbol to mark contexts as prototype-based
+ * Used for type guards and instanceof-like checks
+ */
+export const TRACE_CONTEXT_MARKER = Symbol.for('lmao.TraceContext');
+/**
+ * The shared prototype object for TraceContext.
+ *
+ * Per V8 optimization guidelines:
+ * - Define methods ONCE on prototype, not per-instance
+ * - Use Object.create() for inheritance chains
+ * - Avoid object spreads which break hidden classes
+ */
+export const TraceContextProto = {
+    [TRACE_CONTEXT_MARKER]: true,
+    trace_id: undefined,
+    anchorEpochMicros: undefined,
+    anchorPerfNow: undefined,
+    ff: undefined,
+    span: undefined,
+    _extraKeys: undefined,
+};
+// =============================================================================
+// Type Guard
+// =============================================================================
+/**
+ * Type guard to check if a value is a TraceContext
+ */
+export function isTraceContext(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        TRACE_CONTEXT_MARKER in value &&
+        value[TRACE_CONTEXT_MARKER] === true);
+}

package/dist/lib/traceId.d.ts

@@ -0,0 +1,78 @@
+/**
+ * TraceId - Branded string type for trace identification
+ *
+ * A TraceId is a string that uniquely identifies a distributed trace.
+ * It's validated to be non-empty and at most 128 characters (ASCII).
+ *
+ * Common formats:
+ * - W3C Trace Context: 32 hex chars (e.g., "0af7651916cd43dd8448eb211c80319c")
+ * - OpenTelemetry: same as W3C
+ * - Custom: any string up to 128 chars
+ *
+ * @module traceId
+ */
+/** Maximum length for a trace ID */
+export declare const MAX_TRACE_ID_LENGTH = 128;
+/** Branded type for validated trace IDs */
+export type TraceId = string & {
+    readonly __brand: 'TraceId';
+};
+/**
+ * Validate and create a TraceId from a string.
+ * @throws Error if validation fails
+ */
+export declare function createTraceId(value: string): TraceId;
+/**
+ * Check if a value is a valid TraceId without throwing.
+ */
+export declare function isValidTraceId(value: unknown): value is TraceId;
+/**
+ * Generate a new random TraceId (W3C format: 32 hex chars).
+ */
+export declare function generateTraceId(): TraceId;
+/**
+ * SpanIdentity - Identifies a specific span for external correlation.
+ *
+ * distributed tracing headers, error reporting). Contains the minimal fields needed
+ * to uniquely identify a span within a trace.
+ *
+ * **Usage:**
+ * ```typescript
+ * // Extract from buffer
+ * const identity: SpanIdentity = {
+ *   trace_id: buffer.trace_id,
+ *   span_id: buffer.span_id,
+ *   thread_id: buffer.thread_id,
+ * };
+ *
+ * // Use in signals/messages
+ * signalReportDown({ service, reporter, span: identity });
+ * ```
+ *
+ * **Fields:**
+ * - `trace_id`: 128-bit UUID identifying the entire trace (branded string)
+ * - `span_id`: 32-bit counter unique within the trace
+ * - `thread_id`: 64-bit identifier for execution thread/context
+ *
+ * @see specs/lmao/01b4_span_identity.md for full identity design
+ */
+export interface SpanIdentity {
+    /** Trace ID - 128-bit UUID identifying the entire trace */
+    readonly trace_id: TraceId;
+    /** Span ID - 32-bit counter unique within this trace */
+    readonly span_id: number;
+    /** Thread ID - 64-bit identifier for execution thread/context */
+    readonly thread_id: bigint;
+}
+/**
+ * Extract SpanIdentity from a span buffer.
+ *
+ * @param buffer - Any object with trace_id, span_id, thread_id properties
+ * @returns SpanIdentity for external correlation
+ */
+export declare function extractSpanIdentity(buffer: {
+    trace_id: TraceId;
+    span_id: number;
+    thread_id: bigint;
+}): SpanIdentity;
+//# sourceMappingURL=traceId.d.ts.map

package/dist/lib/traceId.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceId.d.ts","sourceRoot":"","sources":["../../src/lib/traceId.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,oCAAoC;AACpC,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,2CAA2C;AAC3C,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC;AAU/D;;;GAGG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAcpD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAI/D;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CA0BzC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAE3B,wDAAwD;IACxD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,YAAY,CAMnH"}

package/dist/lib/traceId.js

@@ -0,0 +1,87 @@
+/**
+ * TraceId - Branded string type for trace identification
+ *
+ * A TraceId is a string that uniquely identifies a distributed trace.
+ * It's validated to be non-empty and at most 128 characters (ASCII).
+ *
+ * Common formats:
+ * - W3C Trace Context: 32 hex chars (e.g., "0af7651916cd43dd8448eb211c80319c")
+ * - OpenTelemetry: same as W3C
+ * - Custom: any string up to 128 chars
+ *
+ * @module traceId
+ */
+/** Maximum length for a trace ID */
+export const MAX_TRACE_ID_LENGTH = 128;
+function brandTraceId(value) {
+    return value;
+}
+/** Precompiled regex for non-ASCII detection (2x faster than loop) */
+const NON_ASCII_REGEX = /[^\x20-\x7E]/;
+/**
+ * Validate and create a TraceId from a string.
+ * @throws Error if validation fails
+ */
+export function createTraceId(value) {
+    if (typeof value !== 'string') {
+        throw new Error('TraceId must be a string');
+    }
+    if (value.length === 0) {
+        throw new Error('TraceId cannot be empty');
+    }
+    if (value.length > MAX_TRACE_ID_LENGTH) {
+        throw new Error(`TraceId cannot exceed ${MAX_TRACE_ID_LENGTH} characters`);
+    }
+    if (NON_ASCII_REGEX.test(value)) {
+        throw new Error('TraceId must be ASCII printable characters only');
+    }
+    return brandTraceId(value);
+}
+/**
+ * Check if a value is a valid TraceId without throwing.
+ */
+export function isValidTraceId(value) {
+    return (typeof value === 'string' && value.length > 0 && value.length <= MAX_TRACE_ID_LENGTH && !NON_ASCII_REGEX.test(value));
+}
+/**
+ * Generate a new random TraceId (W3C format: 32 hex chars).
+ */
+export function generateTraceId() {
+    const bytes = new Uint8Array(16);
+    if (typeof crypto !== 'undefined' && typeof crypto.getRandomValues === 'function') {
+        crypto.getRandomValues(bytes);
+    }
+    else {
+        try {
+            const nodeCrypto = require('node:crypto');
+            if (nodeCrypto?.randomFillSync) {
+                nodeCrypto.randomFillSync(bytes);
+            }
+        }
+        catch {
+            // Fallback to Math.random (not ideal but works)
+            for (let i = 0; i < 16; i++) {
+                bytes[i] = Math.floor(Math.random() * 256);
+            }
+        }
+    }
+    // Convert to hex string
+    let hex = '';
+    for (let i = 0; i < 16; i++) {
+        hex += bytes[i].toString(16).padStart(2, '0');
+    }
+    return brandTraceId(hex);
+}
+/**
+ * Extract SpanIdentity from a span buffer.
+ *
+ * @param buffer - Any object with trace_id, span_id, thread_id properties
+ * @returns SpanIdentity for external correlation
+ */
+export function extractSpanIdentity(buffer) {
+    return {
+        trace_id: buffer.trace_id,
+        span_id: buffer.span_id,
+        thread_id: buffer.thread_id,
+    };
+}

package/dist/lib/traceRoot.d.ts

@@ -0,0 +1,133 @@
+/**
+ * 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';
+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 declare const TRACE_ROOT_ANCHOR_EPOCH_OFFSET = 0;
+export declare const TRACE_ROOT_ANCHOR_PERF_OFFSET = 8;
+export declare const TRACE_ROOT_TRACE_ID_LEN_OFFSET = 16;
+export declare 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;
+}
+//# sourceMappingURL=traceRoot.d.ts.map

package/dist/lib/traceRoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceRoot.d.ts","sourceRoot":"","sources":["../../src/lib/traceRoot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE1D,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,eAAe,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExH;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,UAAU,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAClC,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACnC,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,mBAAmB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;IAE3C;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE;QACvB,qBAAqB,CACnB,YAAY,EAAE,aAAa,EAC3B,gBAAgB,EAAE,OAAO,EACzB,UAAU,EAAE,OAAO,EACnB,QAAQ,CAAC,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,OAAO,GACf,aAAa,CAAC;QACjB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAAC;KAC5D,CAAC;CACH;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAChD,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAC/C,eAAO,MAAM,8BAA8B,KAAK,CAAC;AACjD,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C;;;;;;GAMG;AACH;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,KAAK,UAAU,CAAC;AAE9F,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAElC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B;;;OAGG;IACH,iBAAiB,IAAI,WAAW,CAAC;IAEjC;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9D;;;;;;OAMG;IACH,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7D;;;;;;;OAOG;IACH,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;CACjE"}

package/dist/lib/traceRoot.es.d.ts

@@ -0,0 +1,75 @@
+/**
+ * TraceRoot - Browser/ES implementation.
+ *
+ * Uses performance.now() for timing with microsecond precision (~5-20μs).
+ * Last 3 digits of nanoseconds are always 000.
+ *
+ * For Node.js with NAPI-optimized writes, use traceRoot.node.ts instead.
+ *
+ * @module traceRoot.es
+ */
+import { Nanoseconds } from '@smoothbricks/arrow-builder';
+import { type TraceId } from './traceId.js';
+import { type ITraceRoot, type TracerLifecycleHooks } from './traceRoot.js';
+import type { AnySpanBuffer } from './types.js';
+/**
+ * TraceRoot - Browser implementation with performance.now() timing.
+ *
+ * Stores anchor data in _system ArrayBuffer for consistency with Node.js layout,
+ * but all timestamp calculations are done in pure JS.
+ */
+export declare 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;
+    private readonly _perfView;
+    constructor(trace_id: TraceId, anchorEpochNanos: bigint, anchorPerfNow: number, tracer: TracerLifecycleHooks);
+    /**
+     * Epoch time in nanoseconds when trace was created.
+     */
+    get anchorEpochNanos(): bigint;
+    /**
+     * High-resolution timer anchor when trace was created (performance.now() value).
+     */
+    get anchorPerfNow(): number;
+    /**
+     * Trace ID for this trace.
+     */
+    get trace_id(): TraceId;
+    /**
+     * Get current timestamp in nanoseconds since Unix epoch.
+     * Uses performance.now() - microsecond precision (last 3 digits = 000).
+     */
+    getTimestampNanos(): Nanoseconds;
+    /**
+     * Write span-start entry to buffer at row 0.
+     *
+     * Pure JS implementation - writes timestamp, entry_type, message, and sets _writeIndex.
+     */
+    writeSpanStart(buffer: AnySpanBuffer, spanName: string): void;
+    /**
+     * Write span-end entry to buffer at row 1.
+     * Writes both timestamp and entry_type.
+     */
+    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.
+     */
+    writeLogEntry(buffer: AnySpanBuffer, entryType: number): number;
+}
+/**
+ * Factory function for creating browser TraceRoot instances.
+ * Pass this to Tracer constructor for browser/ES environments.
+ */
+export declare function createTraceRoot(trace_id: string, tracer: TracerLifecycleHooks): TraceRoot;
+//# sourceMappingURL=traceRoot.es.d.ts.map

package/dist/lib/traceRoot.es.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traceRoot.es.d.ts","sourceRoot":"","sources":["../../src/lib/traceRoot.es.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAC;AAE1D,OAAO,EAAiB,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EACL,KAAK,UAAU,EAKf,KAAK,oBAAoB,EAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAQhD;;;;;GAKG;AACH,qBAAa,SAAU,YAAW,UAAU;IAC1C;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IAEtC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgB;IAC3C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,QAAQ,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB;IAqB5G;;OAEG;IACH,IAAI,gBAAgB,IAAI,MAAM,CAE7B;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,OAAO,CAGtB;IAED;;;OAGG;IACH,iBAAiB,IAAI,WAAW;IAOhC;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAc7D;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAK5D;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;CAOhE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,oBAAoB,GAAG,SAAS,CAIzF"}

package/dist/lib/traceRoot.es.js

@@ -0,0 +1,129 @@
+/**
+ * TraceRoot - Browser/ES implementation.
+ *
+ * Uses performance.now() for timing with microsecond precision (~5-20μs).
+ * Last 3 digits of nanoseconds are always 000.
+ *
+ * For Node.js with NAPI-optimized writes, use traceRoot.node.ts instead.
+ *
+ * @module traceRoot.es
+ */
+import { Nanoseconds } from '@smoothbricks/arrow-builder';
+import { ENTRY_TYPE_SPAN_EXCEPTION, ENTRY_TYPE_SPAN_START } from './schema/systemSchema.js';
+import { createTraceId } from './traceId.js';
+import { TRACE_ROOT_ANCHOR_EPOCH_OFFSET, TRACE_ROOT_ANCHOR_PERF_OFFSET, TRACE_ROOT_TRACE_ID_LEN_OFFSET, TRACE_ROOT_TRACE_ID_OFFSET, } from './traceRoot.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 - Browser implementation with performance.now() timing.
+ *
+ * Stores anchor data in _system ArrayBuffer for consistency with Node.js layout,
+ * but all timestamp calculations are done in pure JS.
+ */
+export class TraceRoot {
+    /**
+     * Raw backing buffer containing anchor timestamps and trace_id.
+     */
+    _system;
+    /**
+     * Tracer reference for lifecycle hooks and event callbacks.
+     */
+    tracer;
+    /**
+     * Cached TypedArray views for fast JS access.
+     */
+    _epochView;
+    _perfView;
+    constructor(trace_id, anchorEpochNanos, anchorPerfNow, tracer) {
+        // 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;
+        // 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() {
+        return this._epochView[0];
+    }
+    /**
+     * High-resolution timer anchor when trace was created (performance.now() value).
+     */
+    get anchorPerfNow() {
+        return this._perfView[0];
+    }
+    /**
+     * Trace ID for this trace.
+     */
+    get trace_id() {
+        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 performance.now() - microsecond precision (last 3 digits = 000).
+     */
+    getTimestampNanos() {
+        const elapsedMs = performance.now() - this._perfView[0];
+        // Convert to nanoseconds (last 3 digits = 000 due to microsecond precision)
+        const elapsedNanos = BigInt(Math.floor(elapsedMs * 1000)) * 1000n;
+        return Nanoseconds.unsafe(this._epochView[0] + elapsedNanos);
+    }
+    /**
+     * Write span-start entry to buffer at row 0.
+     *
+     * Pure JS implementation - writes timestamp, entry_type, message, and sets _writeIndex.
+     */
+    writeSpanStart(buffer, spanName) {
+        // Row 0: span-start
+        buffer.timestamp[0] = this.getTimestampNanos();
+        buffer.entry_type[0] = ENTRY_TYPE_SPAN_START;
+        buffer.message(0, spanName);
+        // Row 1: pre-initialize as span-exception (will be overwritten on ok/err)
+        buffer.entry_type[1] = ENTRY_TYPE_SPAN_EXCEPTION;
+        buffer.timestamp[1] = 0n;
+        // Events start at row 2
+        buffer._writeIndex = 2;
+    }
+    /**
+     * Write span-end entry to buffer at row 1.
+     * Writes both timestamp and entry_type.
+     */
+    writeSpanEnd(buffer, entryType) {
+        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, entryType) {
+        const idx = buffer._writeIndex;
+        buffer.timestamp[idx] = this.getTimestampNanos();
+        buffer.entry_type[idx] = entryType;
+        buffer._writeIndex = idx + 1;
+        return idx;
+    }
+}
+/**
+ * Factory function for creating browser TraceRoot instances.
+ * Pass this to Tracer constructor for browser/ES environments.
+ */
+export function createTraceRoot(trace_id, tracer) {
+    const anchorEpochNanos = BigInt(Date.now()) * 1000000n;
+    const anchorPerfNow = performance.now();
+    return new TraceRoot(createTraceId(trace_id), anchorEpochNanos, anchorPerfNow, tracer);
+}