@livestore/utils-dev 0.4.0-dev.9 → 0.5.0-dev.0

package/src/node/mod.ts

@@ -1,29 +1,29 @@
 import { performance } from 'node:perf_hooks'
 
-import * as OtelNodeSdk from '@effect/opentelemetry/NodeSdk'
-import { IS_BUN, isNonEmptyString } from '@livestore/utils'
-import type { Tracer } from '@livestore/utils/effect'
-import { Config, Effect, FiberRef, Layer, LogLevel, OtelTracer } from '@livestore/utils/effect'
-import { OtelLiveDummy } from '@livestore/utils/node'
 import * as otel from '@opentelemetry/api'
-import { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
-import { PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics'
-import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
+
+import { IS_BUN } from '@livestore/utils'
+import {
+  type Tracer,
+  Config,
+  Context,
+  Effect,
+  Exit,
+  FetchHttpClient,
+  Layer,
+  Option,
+  OtelTracer,
+  Otlp,
+  Schema,
+} from '@livestore/utils/effect'
+import { OtelLiveDummy } from '@livestore/utils/node'
 
 export { OTLPMetricExporter } from '@opentelemetry/exporter-metrics-otlp-http'
 export { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
 export * from './cmd.ts'
-export {
-  type DockerComposeArgs,
-  DockerComposeError,
-  type DockerComposeOperations,
-  DockerComposeService,
-  type LogsOptions,
-  type StartOptions,
-  startDockerComposeServicesScoped,
-} from './DockerComposeService/DockerComposeService.ts'
+export * from './DockerCompose/mod.ts'
 export * as FileLogger from './FileLogger.ts'
+export * from './workspace.ts'
 
 export const OtelLiveHttp = ({
   serviceName,
@@ -39,105 +39,99 @@ export const OtelLiveHttp = ({
   rootSpanAttributes?: Record<string, unknown>
   skipLogUrl?: boolean
   traceNodeBootstrap?: boolean
-} = {}): Layer.Layer<OtelTracer.OtelTracer | Tracer.ParentSpan, never, never> =>
+} = {}): Layer.Layer<OtelTracer.OtelTracer | Tracer.Tracer | Tracer.ParentSpan> =>
   Effect.gen(function* () {
     const configRes = yield* Config.all({
-      exporterUrl: Config.string('OTEL_EXPORTER_OTLP_ENDPOINT').pipe(
-        Config.validate({ message: 'OTEL_EXPORTER_OTLP_ENDPOINT must be set', validation: isNonEmptyString }),
-      ),
-      serviceName: serviceName
-        ? Config.succeed(serviceName)
-        : Config.string('OTEL_SERVICE_NAME').pipe(Config.withDefault('livestore-utils-dev')),
-      rootSpanName: rootSpanName
-        ? Config.succeed(rootSpanName)
-        : Config.string('OTEL_ROOT_SPAN_NAME').pipe(Config.withDefault('RootSpan')),
+      exporterUrl: Config.nonEmptyString('OTEL_EXPORTER_OTLP_ENDPOINT'),
+      serviceName:
+        serviceName !== undefined
+          ? Config.succeed(serviceName)
+          : Config.string('OTEL_SERVICE_NAME').pipe(Config.withDefault('livestore-utils-dev')),
+      rootSpanName:
+        rootSpanName !== undefined
+          ? Config.succeed(rootSpanName)
+          : Config.string('OTEL_ROOT_SPAN_NAME').pipe(Config.withDefault('RootSpan')),
     }).pipe(Effect.option)
 
     if (configRes._tag === 'None') {
       const RootSpanLive = Layer.span('DummyRoot', {})
-      return RootSpanLive.pipe(Layer.provideMerge(OtelLiveDummy)) as any
+      return withTracerReference(RootSpanLive.pipe(Layer.provideMerge(OtelLiveDummy)))
     }
 
     const config = configRes.value
 
-    const resource = { serviceName: config.serviceName }
-
-    const metricReader = new PeriodicExportingMetricReader({
-      exporter: new OTLPMetricExporter({ url: `${config.exporterUrl}/v1/metrics` }),
-      exportIntervalMillis: 1000,
-    })
-
-    const OtelLive = OtelNodeSdk.layer(() => ({
-      resource,
-      metricReader,
-      spanProcessor: new BatchSpanProcessor(
-        new OTLPTraceExporter({ url: `${config.exporterUrl}/v1/traces`, headers: {} }),
-        { scheduledDelayMillis: 50 },
-      ),
-    })).pipe(
-      // If an OpenTelemetry backend is not available, the `OtelNodeSdk` layer
-      // will ignore the error when attempting to connect and emit a debug log
-      // stating the reason for the error (in this case `ECONNREFUSED`). This
-      // can cause problems for programs which rely on clean `stdout` (e.g.
-      // command-line applications). To remedy this, the below code sets the
-      // minimum log level `FiberRef` to `"None"` for the duration of the
-      // `OtelNodeSdk`'s layer constructor.
-      //
-      // This can likely be removed when Livestore is migrated to the Effect
-      // native Otlp exporters.
-      Layer.locally(FiberRef.currentMinimumLogLevel, LogLevel.None),
-    )
+    const OtelLive = Otlp.layerJson({
+      baseUrl: config.exporterUrl,
+      metricsExportInterval: 1000,
+      tracerExportInterval: 50,
+      resource: { serviceName: config.serviceName },
+    }).pipe(Layer.provide(FetchHttpClient.layer))
+    const OtelTracerLive = Layer.succeed(OtelTracer.OtelTracer, otel.trace.getTracer(config.serviceName))
 
     const RootSpanLive = Layer.span(config.rootSpanName, {
       attributes: { config, ...rootSpanAttributes },
-      onEnd: skipLogUrl ? undefined : (span: any) => logTraceUiUrlForSpan()(span.span),
+      onEnd: skipLogUrl === true ? undefined : (span) => logTraceUiUrlForTraceId()(span.traceId),
       parent: parentSpan,
     })
 
-    const layer = yield* Layer.memoize(RootSpanLive.pipe(Layer.provideMerge(OtelLive)))
+    const baseLayer = RootSpanLive.pipe(Layer.provideMerge(Layer.mergeAll(OtelLive, OtelTracerLive)))
 
-    if (traceNodeBootstrap) {
+    const memoMap = yield* Layer.makeMemoMap
+    const layer = Layer.fromBuild((_, scope) => Layer.buildWithMemoMap(baseLayer, memoMap, scope))
+
+    if (traceNodeBootstrap === true && IS_BUN === false) {
       /**
        * Create a span representing the Node.js bootstrap duration.
+       * Note: Skipped in Bun since performance.nodeTiming is not properly supported.
        */
       yield* Effect.gen(function* () {
-        const tracer = yield* OtelTracer.OtelTracer
-        const currentSpan = yield* OtelTracer.currentOtelSpan
-
-        const nodeTiming = performance.nodeTiming
-
-        // TODO get rid of this workaround for Bun once Bun properly supports performance.nodeTiming
-        const startTime = IS_BUN ? nodeTiming.startTime : performance.timeOrigin + nodeTiming.nodeStart
-
-        const bootSpan = tracer.startSpan(
-          'node-bootstrap',
-          {
-            startTime: nodeTiming.nodeStart,
-            attributes: {
-              'node.timing.nodeStart': nodeTiming.nodeStart,
-              'node.timing.environment': nodeTiming.environment,
-              'node.timing.bootstrapComplete': nodeTiming.bootstrapComplete,
-              'node.timing.loopStart': nodeTiming.loopStart,
-              'node.timing.duration': nodeTiming.duration,
-            },
-          },
-          otel.trace.setSpanContext(otel.context.active(), currentSpan.spanContext()),
-        )
-
-        bootSpan.end(startTime + nodeTiming.duration)
+        const tracer = yield* Effect.tracer
+        const currentSpan = yield* Effect.currentSpan
+
+        const { nodeTiming, endAbs, durationAttr } = computeBootstrapTiming()
+
+        const bootSpan = tracer.span({
+          name: 'node-bootstrap',
+          parent: Option.some(currentSpan),
+          annotations: Context.empty(),
+          links: [],
+          startTime: millisToNanos(
+            IS_BUN === true && typeof nodeTiming.nodeStart === 'number'
+              ? nodeTiming.nodeStart
+              : performance.timeOrigin + nodeTiming.nodeStart,
+          ),
+          kind: 'internal',
+          root: false,
+          sampled: true,
+        })
+
+        for (const [key, value] of Object.entries({
+          'node.timing.nodeStart': nodeTiming.nodeStart,
+          'node.timing.environment': nodeTiming.environment,
+          'node.timing.bootstrapComplete': nodeTiming.bootstrapComplete,
+          'node.timing.loopStart': nodeTiming.loopStart,
+          'node.timing.duration': durationAttr,
+        })) {
+          if (value !== undefined) bootSpan.attribute(key, value)
+        }
+
+        bootSpan.end(millisToNanos(endAbs), Exit.void)
       }).pipe(Effect.provide(layer), Effect.orDie)
     }
 
-    return layer
-  }).pipe(Layer.unwrapScoped) as any
+    return withTracerReference(layer)
+  }).pipe(Layer.unwrap)
 
 export const logTraceUiUrlForSpan = (printMsg?: (url: string) => string) => (span: otel.Span) =>
-  getTracingBackendUrl(span).pipe(
+  logTraceUiUrlForTraceId(printMsg)(span.spanContext().traceId)
+
+const logTraceUiUrlForTraceId = (printMsg?: (url: string) => string) => (traceId: string) =>
+  getTracingBackendUrl(traceId).pipe(
     Effect.tap((url) => {
       if (url === undefined) {
         return Effect.logWarning('No tracing backend url found')
       } else {
-        if (printMsg) {
+        if (printMsg !== undefined) {
           return Effect.log(printMsg(url))
         } else {
           return Effect.log(`Trace URL: ${url}`)
@@ -146,25 +140,87 @@ export const logTraceUiUrlForSpan = (printMsg?: (url: string) => string) => (spa
     }),
   )
 
-export const getTracingBackendUrl = (span: otel.Span) =>
+export const getTracingBackendUrl = (traceIdOrSpan: string | otel.Span) =>
   Effect.gen(function* () {
-    const endpoint = yield* Config.string('GRAFANA_ENDPOINT').pipe(Config.option, Effect.orDie)
+    const endpoint = yield* Config.string('GRAFANA_ENDPOINT').pipe(Config.option)
     if (endpoint._tag === 'None') return
 
-    const traceId = span.spanContext().traceId
+    const traceId = typeof traceIdOrSpan === 'string' ? traceIdOrSpan : traceIdOrSpan.spanContext().traceId
 
     // Grafana + Tempo
 
     const grafanaEndpoint = endpoint.value
+    const left = yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown))({
+      datasource: 'tempo',
+      queries: [{ query: traceId, queryType: 'traceql', refId: 'A' }],
+      range: { from: 'now-1h', to: 'now' },
+    })
     const searchParams = new URLSearchParams({
       orgId: '1',
-      left: JSON.stringify({
-        datasource: 'tempo',
-        queries: [{ query: traceId, queryType: 'traceql', refId: 'A' }],
-        range: { from: 'now-1h', to: 'now' },
-      }),
+      left,
     })
 
     // TODO make dynamic via env var
     return `${grafanaEndpoint}/explore?${searchParams.toString()}`
-  })
+  }).pipe(Effect.orDie)
+
+/**
+ * Compute absolute start/end timestamps for the Node.js bootstrap span in a
+ * way that works in both Node and Bun.
+ *
+ * Context: Bun's perf_hooks PerformanceNodeTiming currently throws when
+ * accessing standard PerformanceEntry getters like `startTime` and
+ * `duration`, and some fields differ in semantics (e.g. `nodeStart` appears
+ * as an epoch timestamp rather than an offset). See:
+ * https://github.com/oven-sh/bun/issues/23041
+ *
+ * We therefore avoid the problematic getters and derive absolute timestamps
+ * using fields that exist in both runtimes.
+ *
+ * TODO: Simplify to a single, non-branching computation once the Bun issue
+ * above is fixed and Bun matches Node's semantics for PerformanceNodeTiming.
+ */
+const computeBootstrapTiming = () => {
+  const nodeTiming = performance.nodeTiming
+
+  // Absolute start time in ms since epoch.
+  const startAbs =
+    IS_BUN === true
+      ? typeof nodeTiming.nodeStart === 'number'
+        ? nodeTiming.nodeStart
+        : performance.timeOrigin
+      : performance.timeOrigin + nodeTiming.nodeStart
+
+  // Absolute end time.
+  const endAbs =
+    IS_BUN === true
+      ? (() => {
+          const { loopStart, bootstrapComplete } = nodeTiming
+          if (typeof loopStart === 'number' && loopStart > 0) return startAbs + loopStart
+          if (typeof bootstrapComplete === 'number' && bootstrapComplete >= startAbs) return bootstrapComplete
+          return startAbs + 1
+        })()
+      : startAbs + nodeTiming.duration
+
+  // Duration attribute value for the span.
+  const durationAttr =
+    IS_BUN === true
+      ? (() => {
+          const { loopStart } = nodeTiming
+          return typeof loopStart === 'number' && loopStart > 0 ? loopStart : 0
+        })()
+      : nodeTiming.duration
+
+  return { nodeTiming, startAbs, endAbs, durationAttr } as const
+}
+
+const millisToNanos = (millis: number): bigint => BigInt(Math.round(millis * 1_000_000))
+
+/**
+ * Effect v4 installs `Tracer.Tracer` through a `Context.Reference` fiber ref.
+ * The OTEL layers set that reference at runtime, but their layer output type is
+ * `never`, so we localize the public compatibility assertion here.
+ */
+const withTracerReference = <ROut, E, RIn>(
+  layer: Layer.Layer<ROut, E, RIn>,
+): Layer.Layer<ROut | Tracer.Tracer, E, RIn> => layer as Layer.Layer<ROut | Tracer.Tracer, E, RIn>

package/src/node/workspace.ts

@@ -0,0 +1,45 @@
+import path from 'node:path'
+
+import { shouldNeverHappen } from '@livestore/utils'
+import { Context, Effect, Layer } from '@livestore/utils/effect'
+
+export type WorkspaceInfo = string
+
+/** Current working directory. */
+export class CurrentWorkingDirectory extends Context.Service<CurrentWorkingDirectory, WorkspaceInfo>()(
+  'CurrentWorkingDirectory',
+) {
+  /** Layer that captures the process cwd once. */
+  static live = Layer.effect(
+    CurrentWorkingDirectory,
+    Effect.sync(() => CurrentWorkingDirectory.of(process.cwd())),
+  )
+
+  /** Override CWD for tests or nested invocations. */
+  static fromPath = (cwd: string) => Layer.succeed(CurrentWorkingDirectory, CurrentWorkingDirectory.of(cwd))
+}
+
+/** Livestore workspace root (env required). */
+export class LivestoreWorkspace extends Context.Service<LivestoreWorkspace, WorkspaceInfo>()('LivestoreWorkspace') {
+  /** Resolve from WORKSPACE_ROOT env. */
+  static live = Layer.effect(
+    LivestoreWorkspace,
+    Effect.sync(() => {
+      const root = process.env.WORKSPACE_ROOT ?? shouldNeverHappen('WORKSPACE_ROOT is not set')
+      return LivestoreWorkspace.of(root)
+    }),
+  )
+
+  /** Provide a fixed Livestore root. */
+  static fromPath = (root: string) => Layer.succeed(LivestoreWorkspace, LivestoreWorkspace.of(root))
+
+  /** Derive a CurrentWorkingDirectory layer from the Livestore workspace root (with optional subpath) */
+  static toCwd = (/** Relative path to the Livestore workspace root */ subPath?: string) =>
+    Layer.effect(
+      CurrentWorkingDirectory,
+      Effect.gen(function* () {
+        const root = yield* LivestoreWorkspace
+        return CurrentWorkingDirectory.of(path.join(root, subPath ?? ''))
+      }),
+    )
+}

package/src/node-vitest/Vitest.test.ts

@@ -1,6 +1,11 @@
-import { Effect, FastCheck } from '@livestore/utils/effect'
+import { Effect, FastCheck, Schema } from '@livestore/utils/effect'
+
 import * as Vitest from './Vitest.ts'
 
+export class TestError extends Schema.TaggedError<TestError>()('TestError', {
+  message: Schema.String,
+}) {}
+
 // Demonstrate enhanced asProp functionality with clear shrinking progress
 // This showcases the fix for the "Run 26/6" bug and accurate shrinking detection
 
@@ -9,14 +14,14 @@ Vitest.describe('Vitest.asProp', () => {
 
   // Always-passing test - should only show initial phase
   Vitest.asProp(
-    Vitest.scopedLive,
+    Vitest.live,
     'always-pass test (shows only initial runs)',
     [IntArbitrary],
     (properties, _ctx, enhanced) =>
       Effect.gen(function* () {
         const [value] = properties
         if (value === undefined) {
-          return yield* Effect.fail(new Error('Value is undefined'))
+          return yield* new TestError({ message: 'Value is undefined' })
         }
 
         console.log(
@@ -33,17 +38,36 @@ Vitest.describe('Vitest.asProp', () => {
     { fastCheck: { numRuns: 4 } },
   )
 
+  Vitest.asProp(
+    Vitest.live,
+    'converts record-form schemas to arbitraries',
+    {
+      count: Schema.Int,
+      payload: Schema.Struct({
+        label: Schema.String,
+        note: Schema.optional(Schema.String),
+      }),
+    },
+    ({ count, payload }) =>
+      Effect.sync(() => {
+        Vitest.expect(Number.isInteger(count)).toBe(true)
+        Vitest.expect(typeof payload.label).toBe('string')
+        Vitest.expect(payload.note === undefined || typeof payload.note === 'string').toBe(true)
+      }),
+    { fastCheck: { numRuns: 10 } },
+  )
+
   // Failing test - should show initial + shrinking phases
   let alreadyFailed = false
   Vitest.asProp(
-    Vitest.scopedLive,
+    Vitest.live,
     'failing test (shows initial runs + shrinking)',
     [IntArbitrary],
     (properties, ctx, enhanced) =>
       Effect.gen(function* () {
         const [value] = properties
         if (value === undefined) {
-          return yield* Effect.fail(new Error('Value is undefined'))
+          return yield* new TestError({ message: 'Value is undefined' })
         }
 
         const displayInfo =
@@ -59,10 +83,10 @@ Vitest.describe('Vitest.asProp', () => {
         // Fail when value is greater than 80 to trigger shrinking
         if (value > 80) {
           alreadyFailed = true
-          return yield* Effect.fail(new Error(`Value ${value} is too large (> 80)`))
+          return yield* new TestError({ message: `Value ${value} is too large (> 80)` })
         }
 
-        if (alreadyFailed && enhanced._tag === 'shrinking') {
+        if (alreadyFailed === true && enhanced._tag === 'shrinking') {
           ctx.skip("For the sake of this test, we don't want to fail but want to skip")
           return
         }
@@ -74,14 +98,14 @@ Vitest.describe('Vitest.asProp', () => {
 
   // Test with endOnFailure: true - should not show shrinking
   Vitest.asProp(
-    Vitest.scopedLive,
+    Vitest.live,
     'failing test with endOnFailure (no shrinking)',
     [IntArbitrary],
     (properties, _ctx, enhanced) =>
       Effect.gen(function* () {
         const [value] = properties
         if (value === undefined) {
-          return yield* Effect.fail(new Error('Value is undefined'))
+          return yield* new TestError({ message: 'Value is undefined' })
         }
 
         console.log(
@@ -91,7 +115,7 @@ Vitest.describe('Vitest.asProp', () => {
 
         // This will fail but shrinking is disabled
         if (value > 50) {
-          yield* Effect.fail(new Error(`Value ${value} is too large (> 50) - but no shrinking!`))
+          return yield* new TestError({ message: `Value ${value} is too large (> 50) - but no shrinking!` })
         }
 
         return