@smoothbricks/lmao 0.1.0

package/package.json

@@ -0,0 +1,193 @@
+{
+  "name": "@smoothbricks/lmao",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "development": "./src/index.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "development": "./src/node.ts",
+      "import": "./dist/node.js",
+      "default": "./dist/node.js"
+    },
+    "./es": {
+      "types": "./dist/es.d.ts",
+      "development": "./src/es.ts",
+      "import": "./dist/es.js",
+      "default": "./dist/es.js"
+    },
+    "./tracers": {
+      "types": "./dist/lib/tracers/index.d.ts",
+      "development": "./src/lib/tracers/index.ts",
+      "import": "./dist/lib/tracers/index.js",
+      "default": "./dist/lib/tracers/index.js"
+    },
+    "./errors": {
+      "types": "./dist/lib/errors/index.d.ts",
+      "development": "./src/lib/errors/index.ts",
+      "import": "./dist/lib/errors/index.js",
+      "default": "./dist/lib/errors/index.js"
+    },
+    "./errors/Blocked": {
+      "types": "./dist/lib/errors/Blocked.d.ts",
+      "development": "./src/lib/errors/Blocked.ts",
+      "import": "./dist/lib/errors/Blocked.js",
+      "default": "./dist/lib/errors/Blocked.js"
+    },
+    "./errors/RetriesExhausted": {
+      "types": "./dist/lib/errors/RetriesExhausted.d.ts",
+      "development": "./src/lib/errors/RetriesExhausted.ts",
+      "import": "./dist/lib/errors/RetriesExhausted.js",
+      "default": "./dist/lib/errors/RetriesExhausted.js"
+    },
+    "./errors/CodeError": {
+      "types": "./dist/lib/errors/CodeError.d.ts",
+      "development": "./src/lib/errors/CodeError.ts",
+      "import": "./dist/lib/errors/CodeError.js",
+      "default": "./dist/lib/errors/CodeError.js"
+    },
+    "./errors/retry-policy": {
+      "types": "./dist/lib/errors/retry-policy.d.ts",
+      "development": "./src/lib/errors/retry-policy.ts",
+      "import": "./dist/lib/errors/retry-policy.js",
+      "default": "./dist/lib/errors/retry-policy.js"
+    },
+    "./errors/Transient": {
+      "types": "./dist/lib/errors/Transient.d.ts",
+      "development": "./src/lib/errors/Transient.ts",
+      "import": "./dist/lib/errors/Transient.js",
+      "default": "./dist/lib/errors/Transient.js"
+    },
+    "./sqlite": {
+      "types": "./dist/lib/sqlite/index.d.ts",
+      "development": "./src/lib/sqlite/index.ts",
+      "import": "./dist/lib/sqlite/index.js",
+      "default": "./dist/lib/sqlite/index.js"
+    },
+    "./sqlite/node": {
+      "types": "./dist/lib/sqlite/sqlite-node.d.ts",
+      "development": "./src/lib/sqlite/sqlite-node.ts",
+      "import": "./dist/lib/sqlite/sqlite-node.js",
+      "default": "./dist/lib/sqlite/sqlite-node.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "development": "./src/testing.ts",
+      "import": "./dist/testing.js",
+      "default": "./dist/testing.js"
+    },
+    "./testing/bun": {
+      "types": "./dist/lib/testing/bun-harness.d.ts",
+      "bun": "./src/lib/testing/bun-harness.ts",
+      "development": "./src/lib/testing/bun-harness.ts",
+      "import": "./dist/lib/testing/bun-harness.js",
+      "default": "./dist/lib/testing/bun-harness.js"
+    },
+    "./testing/vitest": {
+      "types": "./dist/lib/testing/vitest-harness.d.ts",
+      "development": "./src/lib/testing/vitest-harness.ts",
+      "import": "./dist/lib/testing/vitest-harness.js",
+      "default": "./dist/lib/testing/vitest-harness.js"
+    },
+    "./bun/preload": {
+      "bun": "./src/bun/preload.ts",
+      "development": "./src/bun/preload.ts",
+      "default": "./dist/bun/preload.js"
+    },
+    "./bun/trace-preload": {
+      "bun": "./src/bun/trace-preload.ts",
+      "development": "./src/bun/trace-preload.ts",
+      "default": "./dist/bun/trace-preload.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "@msgpack/msgpack": "^3.1.3",
+    "@neophi/sieve-cache": "^1.5.0",
+    "@smoothbricks/arrow-builder": "0.0.1",
+    "@smoothbricks/validation": "0.0.1",
+    "@uwdata/flechette": "^2.3.0",
+    "tslib": "^2.8.1"
+  },
+  "scripts": {
+    "bench": "bun run benchmarks/*.bench.ts",
+    "bench:wasm": "bun run benchmarks/js-vs-wasm.bench.ts",
+    "build:wasm": "zig build -Doptimize=ReleaseSmall"
+  },
+  "nx": {
+    "sourceRoot": "packages/lmao/src",
+    "projectType": "library",
+    "targets": {
+      "lint": {},
+      "typecheck": {
+        "dependsOn": [
+          "build",
+          "^typecheck"
+        ]
+      },
+      "build:wasm": {
+        "inputs": [
+          "{projectRoot}/src/**/*.zig",
+          "{projectRoot}/build.zig",
+          "{projectRoot}/build.zig.zon"
+        ],
+        "executor": "nx:run-commands",
+        "options": {
+          "command": "zig build -Doptimize=ReleaseSmall",
+          "cwd": "packages/lmao"
+        }
+      },
+      "build": {
+        "dependsOn": [
+          "^build",
+          "build:wasm"
+        ]
+      },
+      "test": {
+        "executor": "nx:run-commands",
+        "options": {
+          "command": "bun test",
+          "cwd": "packages/lmao"
+        }
+      }
+    },
+    "tags": [
+      "npm:public"
+    ]
+  },
+  "devDependencies": {
+    "fast-check": "^4.4.0",
+    "vitest": "^3.2.4"
+  },
+  "peerDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smoothbricks/codebase.git",
+    "directory": "packages/lmao"
+  }
+}

package/src/bun/preload.ts

@@ -0,0 +1,11 @@
+/**
+ * Bun runtime preload — registers Typia validation codegen plugin.
+ *
+ * Re-exports from @smoothbricks/validation which owns the Typia integration.
+ * Packages that cannot depend on lmao should use @smoothbricks/validation/bun/preload directly.
+ *
+ * Usage in bunfig.toml:
+ *   preload = ["@smoothbricks/lmao/bun/preload"]
+ */
+
+import '@smoothbricks/validation/bun/preload';

package/src/bun/trace-preload.ts

@@ -0,0 +1,14 @@
+/**
+ * Bun test tracing preload.
+ *
+ * Registers LMAO SQLite-backed test tracing after the Typia preload has already
+ * been registered in bunfig.
+ */
+
+import { join } from 'node:path';
+import { autoSetupBunTestTracing } from '../lib/testing/bun-harness.js';
+
+// WHY: Find the monorepo packages dir relative to this file's location.
+// This file lives at packages/lmao/src/bun/trace-preload.ts (4 levels up to monorepo root).
+const monorepoRoot = join(import.meta.dir, '..', '..', '..', '..');
+await autoSetupBunTestTracing({ packagesDir: join(monorepoRoot, 'packages') });

package/src/es.ts

@@ -0,0 +1,11 @@
+/**
+ * ES/Browser entry point for @smoothbricks/lmao/es
+ * Uses performance.now() for high-precision timestamps
+ * Works in browsers, Deno, Cloudflare Workers, etc.
+ */
+
+// Re-export all main functionality
+export * from './index.js';
+
+// Export browser-specific TraceRoot factory for Tracer construction
+export { createTraceRoot } from './lib/traceRoot.es.js';

package/src/index.ts

@@ -0,0 +1,194 @@
+// Main integration API - GREENFIELD - NO BACKWARDS COMPAT
+
+// =============================================================================
+// Primary API: defineOpContext (Op-Centric API)
+// =============================================================================
+
+// Op-Centric API - the module system (includes schema utilities and types)
+export * from './lib/defineOpContext.js';
+
+// Op class - used internally by defineOp()
+export { Op } from './lib/op.js';
+
+// =============================================================================
+// Result Types
+// =============================================================================
+
+export { Blocked, type BlockedConfig, type BlockedReason } from './lib/errors/Blocked.js';
+export type { Result, TaggedError, TaggedErrorConstructor } from './lib/result.js';
+export { defineCodeError, Err, hasErrorCode, Ok } from './lib/result.js';
+
+// Tagged Error Types - tree-shakable subpath exports:
+// import { Blocked } from '@smoothbricks/lmao/errors/Blocked'
+// import { RetriesExhausted } from '@smoothbricks/lmao/errors/RetriesExhausted'
+
+// =============================================================================
+// TraceContext Types
+// =============================================================================
+
+export type { RootSpanFn, TraceContext, TraceContextSystem } from './lib/traceContext.js';
+export { isTraceContext, TRACE_CONTEXT_MARKER, TraceContextProto } from './lib/traceContext.js';
+
+// =============================================================================
+// SpanContext Types
+// =============================================================================
+
+export type { FluentLogEntry, SpanContext, SpanFn, SpanLogger } from './lib/spanContext.js';
+export { isSpanContext, SPAN_CONTEXT_MARKER } from './lib/spanContext.js';
+
+// =============================================================================
+// LogAPI - Simple logging interface for contexts without SpanBuffer access
+// =============================================================================
+
+export type { LogAPI } from './lib/logApi.js';
+export { noopLogAPI } from './lib/logApi.js';
+
+// =============================================================================
+// System Schema & Entry Type Constants
+// =============================================================================
+
+export {
+  // Buffer metrics (utilization-based capacity tuning)
+  ENTRY_TYPE_BUFFER_CAPACITY,
+  ENTRY_TYPE_BUFFER_SPANS,
+  ENTRY_TYPE_BUFFER_WRITES,
+  ENTRY_TYPE_DEBUG,
+  ENTRY_TYPE_ERROR,
+  // Feature flags
+  ENTRY_TYPE_FF_ACCESS,
+  ENTRY_TYPE_FF_USAGE,
+  ENTRY_TYPE_INFO,
+  // Lookup
+  ENTRY_TYPE_NAMES,
+  ENTRY_TYPE_OP_DURATION_ERR,
+  ENTRY_TYPE_OP_DURATION_MAX,
+  ENTRY_TYPE_OP_DURATION_MIN,
+  ENTRY_TYPE_OP_DURATION_OK,
+  ENTRY_TYPE_OP_DURATION_TOTAL,
+  ENTRY_TYPE_OP_ERRORS,
+  ENTRY_TYPE_OP_EXCEPTIONS,
+  // Op metrics
+  ENTRY_TYPE_OP_INVOCATIONS,
+  // Period markers
+  ENTRY_TYPE_PERIOD_START,
+  ENTRY_TYPE_SPAN_ERR,
+  ENTRY_TYPE_SPAN_EXCEPTION,
+  ENTRY_TYPE_SPAN_OK,
+  // Span lifecycle
+  ENTRY_TYPE_SPAN_START,
+  // Log levels (ordered by verbosity)
+  ENTRY_TYPE_TRACE,
+  ENTRY_TYPE_WARN,
+  mergeWithSystemSchema,
+  // Schema helpers
+  systemSchema,
+} from './lib/schema/systemSchema.js';
+
+// =============================================================================
+// Schema Core Types (re-exported from arrow-builder)
+// =============================================================================
+
+export type { Input, Output, Schema, SchemaFields, SchemaType, SchemaWithMetadata } from '@smoothbricks/arrow-builder';
+
+// =============================================================================
+// Schema System (additional exports not in defineOpContext)
+// Note: defineOpContext already re-exports S, defineFeatureFlags, defineLogSchema, LogSchema
+// =============================================================================
+
+export * from './lib/schema/evaluator.js';
+export * from './lib/schema/extend.js';
+export * from './lib/schema/typeGuards.js';
+
+// =============================================================================
+// Code Generation (for advanced use)
+// =============================================================================
+
+export type { ResultWriter, TagWriter } from './lib/codegen/fixedPositionWriterGenerator.js';
+export { createResultWriter, createTagWriter } from './lib/codegen/fixedPositionWriterGenerator.js';
+export type { BaseSpanLogger, SpanLoggerImpl } from './lib/codegen/spanLoggerGenerator.js';
+export { createSpanLogger, createSpanLoggerClass } from './lib/codegen/spanLoggerGenerator.js';
+
+// =============================================================================
+// SpanBuffer & Arrow Conversion
+// =============================================================================
+
+export * from './lib/convertToArrow.js';
+export * from './lib/spanBuffer.js';
+export * from './lib/types.js';
+
+// =============================================================================
+// Flush Scheduler
+// =============================================================================
+
+export * from './lib/flushScheduler.js';
+
+// =============================================================================
+// Buffer Strategy
+// =============================================================================
+
+export type { BufferStrategy } from './lib/bufferStrategy.js';
+export { JsBufferStrategy } from './lib/JsBufferStrategy.js';
+
+// =============================================================================
+// Tracer
+// =============================================================================
+
+export type { OpContextBinding } from './lib/opContext/types.js';
+export { type TraceFn, type TraceOverrides, Tracer, type TracerOptions } from './lib/tracer.js';
+export { ArrayQueueTracer } from './lib/tracers/ArrayQueueTracer.js';
+export { CompositeTracer } from './lib/tracers/CompositeTracer.js';
+// Concrete tracer implementations
+export { NoOpTracer } from './lib/tracers/NoOpTracer.js';
+export { SQLiteAsyncTracer, SQLiteTracer } from './lib/tracers/SQLiteTracer.js';
+export { StdioTracer } from './lib/tracers/StdioTracer.js';
+export { type StatsSnapshot, TestTracer } from './lib/tracers/TestTracer.js';
+
+// =============================================================================
+// Library Integration
+// =============================================================================
+
+export * from './lib/library.js';
+
+// =============================================================================
+// Archive Data-Plane Primitives
+// =============================================================================
+
+export * from './lib/archive/index.js';
+
+// =============================================================================
+// Thread ID Generation
+// =============================================================================
+
+export {
+  _resetThreadId,
+  copyThreadIdTo,
+  getThreadId,
+  THREAD_ID_BYTES,
+  writeThreadIdToUint64Array,
+} from './lib/threadId.js';
+
+// =============================================================================
+// Trace ID
+// =============================================================================
+
+export {
+  createTraceId,
+  extractSpanIdentity,
+  generateTraceId,
+  isValidTraceId,
+  MAX_TRACE_ID_LENGTH,
+  type SpanIdentity,
+  type TraceId,
+} from './lib/traceId.js';
+
+// =============================================================================
+// TraceRoot (Platform-specific)
+// =============================================================================
+
+export type { ITraceRoot, TraceRootFactory, TracerLifecycleHooks } from './lib/traceRoot.js';
+
+// =============================================================================
+// UTF-8 Cache (for Arrow conversion)
+// =============================================================================
+
+export * from './lib/utf8Cache.js';

package/src/lib/JsBufferStrategy.ts

@@ -0,0 +1,102 @@
+/**
+ * JsBufferStrategy - Default buffer strategy using JavaScript TypedArrays.
+ *
+ * Uses GC-managed memory with zero-copy Arrow conversion via flechette.
+ *
+ * Memory characteristics:
+ * - Buffers are regular JS objects with TypedArray properties
+ * - GC handles deallocation (no explicit release needed)
+ * - Arrow conversion shares ArrayBuffer references (zero-copy)
+ *
+ * @module JsBufferStrategy
+ */
+
+import type { Table } from '@uwdata/flechette';
+import type { BufferStrategy } from './bufferStrategy.js';
+import { convertSpanTreeToArrowTable } from './convertToArrow.js';
+import type { OpMetadata } from './opContext/opTypes.js';
+import type { LogSchema } from './schema/LogSchema.js';
+import {
+  createChildSpanBuffer as createChildSpanBufferImpl,
+  createOverflowBuffer as createOverflowBufferImpl,
+  createSpanBuffer as createSpanBufferImpl,
+  getSpanBufferClass,
+  type SpanBufferConstructor,
+} from './spanBuffer.js';
+import type { ITraceRoot } from './traceRoot.js';
+import type { AnySpanBuffer, SpanBuffer } from './types.js';
+
+function isSpanBufferConstructorForSchema<TSchema extends LogSchema>(
+  ctor: SpanBufferConstructor | undefined,
+  schema: TSchema,
+): ctor is SpanBufferConstructor<TSchema> {
+  return ctor !== undefined && ctor.schema === schema;
+}
+
+/**
+ * JsBufferStrategy - Default buffer strategy using GC-managed TypedArrays.
+ *
+ * This is the standard strategy for most use cases:
+ * - Simple memory model (GC handles cleanup)
+ * - Zero-copy Arrow conversion (shares ArrayBuffer references)
+ * - No explicit release needed (but releaseBuffer is a no-op)
+ *
+ * @example
+ * ```typescript
+ * const strategy = new JsBufferStrategy<MySchema>();
+ * const tracer = new StdioTracer(binding, strategy, options);
+ * ```
+ */
+export class JsBufferStrategy<T extends LogSchema = LogSchema> implements BufferStrategy<T> {
+  /**
+   * Cache of SpanBuffer classes per schema.
+   * Populated lazily on first buffer creation.
+   */
+  private spanBufferClassCache = new WeakMap<LogSchema, SpanBufferConstructor>();
+
+  /**
+   * Get or create SpanBuffer class for a schema.
+   */
+  private getSpanBufferClassForSchema<TSchema extends LogSchema>(schema: TSchema): SpanBufferConstructor<TSchema> {
+    let cached = this.spanBufferClassCache.get(schema);
+    if (!cached) {
+      cached = getSpanBufferClass(schema);
+      this.spanBufferClassCache.set(schema, cached);
+    }
+    if (!isSpanBufferConstructorForSchema(cached, schema)) {
+      throw new TypeError('Cached SpanBuffer class does not match schema');
+    }
+    return cached;
+  }
+
+  createSpanBuffer(schema: T, traceRoot: ITraceRoot, opMetadata: OpMetadata, capacity?: number): SpanBuffer<T> {
+    return createSpanBufferImpl(schema, traceRoot, opMetadata, capacity);
+  }
+
+  createChildSpanBuffer(
+    parentBuffer: SpanBuffer<T>,
+    callsiteMetadata: OpMetadata,
+    opMetadata: OpMetadata,
+    capacity?: number,
+    schema?: T,
+  ): SpanBuffer<T> {
+    // Use provided schema (for cross-library calls) or parent's schema
+    const childSchema = schema ?? parentBuffer._logSchema;
+    const SpanBufferClass = this.getSpanBufferClassForSchema(childSchema);
+    return createChildSpanBufferImpl(parentBuffer, SpanBufferClass, callsiteMetadata, opMetadata, capacity);
+  }
+
+  createOverflowBuffer(buffer: SpanBuffer<T>): SpanBuffer<T> {
+    return createOverflowBufferImpl(buffer);
+  }
+
+  toArrowTable(buffer: AnySpanBuffer): Table {
+    // Uses existing tree conversion with shared dictionaries
+    return convertSpanTreeToArrowTable(buffer);
+  }
+
+  releaseBuffer(_buffer: AnySpanBuffer): void {
+    // No-op for JS strategy - GC handles memory
+    // The buffer will be collected when no references remain
+  }
+}