@livestore/utils 0.4.0-dev.2 → 0.4.0-dev.20

package/src/effect/Debug.ts

@@ -0,0 +1,375 @@
+import * as C from '@effect/experimental/DevTools/Client'
+import type * as Domain from '@effect/experimental/DevTools/Domain'
+import { Duration, Schedule } from 'effect'
+import * as Console from 'effect/Console'
+import * as Effect from 'effect/Effect'
+import { pipe } from 'effect/Function'
+import * as Graph from 'effect/Graph'
+import * as Layer from 'effect/Layer'
+import * as Option from 'effect/Option'
+
+interface SpanNodeInfo {
+  readonly span: Domain.ParentSpan
+  readonly events: readonly Domain.SpanEvent[]
+}
+
+export type SpanNodeGraph = Graph.Graph<SpanNodeInfo, any>
+
+class DebugInfo extends Effect.Service<DebugInfo>()('@mattiamanzati/debug/DebugInfo', {
+  effect: Effect.sync(() => ({
+    mutableGraph: Graph.beginMutation(Graph.directed<SpanNodeInfo, any>()),
+    nodeIdBySpanId: new Map<string, number>(),
+  })),
+}) {}
+
+const layerClientInMemoryGraph = Layer.effect(
+  C.Client,
+  Effect.gen(function* () {
+    const { mutableGraph, nodeIdBySpanId } = yield* DebugInfo
+
+    function ensureNode(traceId: string, spanId: string) {
+      const existingNodeId = nodeIdBySpanId.get(spanId)
+      if (existingNodeId !== undefined) return existingNodeId
+      const nodeId = Graph.addNode(mutableGraph, {
+        span: { _tag: 'ExternalSpan', spanId, traceId, sampled: false },
+        events: [],
+      })
+      nodeIdBySpanId.set(spanId, nodeId)
+      return nodeId
+    }
+
+    function upgradeInfo(prev: Domain.ParentSpan, next: Domain.ParentSpan): [Domain.ParentSpan, boolean] {
+      if (prev._tag === 'ExternalSpan' && next._tag === 'Span') return [next, true]
+      if (prev._tag === 'Span' && next._tag === 'ExternalSpan') return [prev, false]
+      if (prev._tag === 'Span' && prev.status._tag === 'Ended') return [prev, false]
+      return [next, false]
+    }
+
+    function addNode(span: Domain.ParentSpan) {
+      const nodeId = ensureNode(span.traceId, span.spanId)
+      Graph.updateNode(mutableGraph, nodeId, (previousInfo) => {
+        const [latestInfo, upgraded] = upgradeInfo(previousInfo.span, span)
+        if (upgraded && latestInfo._tag === 'Span' && Option.isSome(latestInfo.parent)) {
+          const parentNodeId = addNode(latestInfo.parent.value)
+          Graph.addEdge(mutableGraph, parentNodeId, nodeId, undefined)
+        }
+        return { ...previousInfo, span: latestInfo }
+      })
+      return nodeId
+    }
+
+    function addEvent(event: Domain.SpanEvent) {
+      const nodeId = ensureNode(event.traceId, event.spanId)
+      Graph.updateNode(mutableGraph, nodeId, (previousInfo) => ({
+        ...previousInfo,
+        events: [...previousInfo.events, event],
+      }))
+    }
+
+    return C.Client.of({
+      unsafeAddSpan: (span) => {
+        switch (span._tag) {
+          case 'SpanEvent':
+            return addEvent(span)
+          case 'Span':
+            return addNode(span)
+        }
+      },
+    })
+  }),
+)
+
+export const layerDebug = pipe(
+  C.makeTracer,
+  Effect.map(Layer.setTracer),
+  Layer.unwrapEffect,
+  Layer.provide(layerClientInMemoryGraph),
+  Layer.provideMerge(DebugInfo.Default),
+)
+
+function formatDuration(startTime: bigint, endTime: bigint | undefined): string {
+  if (endTime === undefined) return 'running'
+  const durationMs = Number(endTime - startTime) / 1000000 // Convert nanoseconds to milliseconds
+  if (durationMs < 1000) return `${durationMs.toFixed(0)}ms`
+  if (durationMs < 60000) return `${(durationMs / 1000).toFixed(2)}s`
+  return `${(durationMs / 60000).toFixed(2)}m`
+}
+
+function getSpanName(span: Domain.ParentSpan): string {
+  if (span._tag === 'ExternalSpan') return `[external] ${span.spanId}`
+  return span.name
+}
+
+function getSpanStatus(span: Domain.ParentSpan): string {
+  if (span._tag === 'ExternalSpan') return '?'
+  if (span.status._tag === 'Ended') return '✓'
+  return '●'
+}
+
+function getSpanDuration(span: Domain.ParentSpan): string {
+  if (span._tag === 'ExternalSpan') return ''
+  const endTime = span.status._tag === 'Ended' ? span.status.endTime : undefined
+  return formatDuration(span.status.startTime, endTime)
+}
+
+/**
+ * Filters a graph by keeping only nodes that match the predicate or have descendants that match.
+ * This ensures parent nodes are included even if they don't match, as long as they have matching descendants.
+ *
+ * @param graph - The graph to filter
+ * @param predicate - A function that tests whether a node should be included
+ * @returns A new filtered graph containing only matching nodes and their ancestors
+ */
+function filterGraphWithAncestors<N, E>(
+  graph: Graph.Graph<N, E>,
+  predicate: (nodeData: N, nodeId: number) => boolean,
+): Graph.Graph<N, E> {
+  // Find all root nodes (nodes with no incoming edges)
+  const rootNodes = Array.from(Graph.indices(Graph.externals(graph, { direction: 'incoming' })))
+
+  const shouldInclude = new Map<number, boolean>()
+
+  // Use postorder DFS to evaluate children before parents
+  for (const rootId of rootNodes) {
+    for (const nodeId of Graph.indices(Graph.dfsPostOrder(graph, { startNodes: [rootId], direction: 'outgoing' }))) {
+      const node = Graph.getNode(graph, nodeId)
+      if (Option.isNone(node)) continue
+
+      const matchesPredicate = predicate(node.value, nodeId)
+
+      // Check if any children should be included
+      const children = Graph.neighborsDirected(graph, nodeId, 'outgoing')
+      const hasMatchingChildren = children.some((childId) => shouldInclude.get(childId) === true)
+
+      const include = matchesPredicate || hasMatchingChildren
+      shouldInclude.set(nodeId, include)
+    }
+  }
+
+  // Create a filtered copy of the graph
+  return Graph.mutate(graph, (mutable) => {
+    for (const [nodeId] of mutable.nodes) {
+      if (shouldInclude.get(nodeId) === true) continue
+      Graph.removeNode(mutable, nodeId)
+    }
+  })
+}
+
+function renderNode(graph: SpanNodeGraph, nodeId: number, prefix = '', isLast = true): string[] {
+  const node = Graph.getNode(graph, nodeId)
+  if (Option.isNone(node)) return []
+
+  const info = node.value
+  const status = getSpanStatus(info.span)
+  const name = getSpanName(info.span)
+  const duration = getSpanDuration(info.span)
+  const durationStr = duration ? ` ${duration}` : ''
+
+  const connector = isLast ? '└─ ' : '├─ '
+  const lines: string[] = [`${prefix}${connector}${status} ${name}${durationStr}`]
+
+  // Get children
+  const children = Graph.neighborsDirected(graph, nodeId, 'outgoing')
+  const childCount = children.length
+
+  children.forEach((childId: number, index: number) => {
+    const isLastChild = index === childCount - 1
+    const childPrefix = prefix + (isLast ? '  ' : '│ ')
+    const childLines = renderNode(graph, childId, childPrefix, isLastChild)
+    lines.push(...childLines)
+  })
+
+  return lines
+}
+
+interface ChromeTraceEvent {
+  name: string
+  cat: string
+  ph: string // Phase: 'B' for begin, 'E' for end
+  ts: number // Timestamp in microseconds
+  pid: number // Process ID
+  tid: number // Thread ID
+  args?: Record<string, unknown>
+}
+
+/**
+ * Converts a span node to Chrome Trace Events (Begin and End)
+ */
+function spanToTraceEvents(span: Domain.ParentSpan, _nodeId: number, processId = 1): ChromeTraceEvent[] {
+  const events: ChromeTraceEvent[] = []
+
+  if (span._tag === 'ExternalSpan') {
+    // External spans don't have timing info, skip them
+    return events
+  }
+
+  const name = span.name
+  const threadId = 1 // Could use spanId hash or other identifier
+
+  // Begin event
+  const startTimeUs = Number(span.status.startTime) / 1000 // Convert nanoseconds to microseconds
+  events.push({
+    name,
+    cat: 'span',
+    ph: 'B',
+    ts: startTimeUs,
+    pid: processId,
+    tid: threadId,
+    args: {
+      spanId: span.spanId,
+      traceId: span.traceId,
+      attributes: Object.fromEntries(span.attributes),
+    },
+  })
+
+  // End event (only if span has ended)
+  if (span.status._tag === 'Ended') {
+    const endTimeUs = Number(span.status.endTime) / 1000 // Convert nanoseconds to microseconds
+    events.push({
+      name,
+      cat: 'span',
+      ph: 'E',
+      ts: endTimeUs,
+      pid: processId,
+      tid: threadId,
+    })
+  }
+
+  return events
+}
+
+/**
+ * Traverses the graph and collects all trace events
+ */
+function collectTraceEvents(graph: SpanNodeGraph, rootNodes: number[]): ChromeTraceEvent[] {
+  const events: ChromeTraceEvent[] = []
+
+  // Use DFS to traverse all nodes
+  for (const rootId of rootNodes) {
+    for (const nodeId of Graph.indices(Graph.dfs(graph, { startNodes: [rootId], direction: 'outgoing' }))) {
+      const node = Graph.getNode(graph, nodeId)
+      if (Option.isNone(node)) continue
+
+      const nodeEvents = spanToTraceEvents(node.value.span, nodeId)
+      events.push(...nodeEvents)
+    }
+  }
+
+  // Sort events by timestamp
+  events.sort((a, b) => a.ts - b.ts)
+
+  return events
+}
+
+export interface LogTreeOptions {
+  readonly regex?: RegExp
+  readonly title?: string
+}
+
+export const logTree = (options: LogTreeOptions = {}) =>
+  Effect.gen(function* () {
+    const maybeInfo = yield* Effect.serviceOption(DebugInfo)
+    if (Option.isNone(maybeInfo))
+      return yield* Console.log(
+        '(no debug info provided! To show the tree, provide the layerDebug layer in the root of your program)',
+      )
+
+    const { mutableGraph } = maybeInfo.value
+    const graph = Graph.endMutation(mutableGraph)
+
+    // Find root nodes (nodes with no incoming edges) using externals
+    const rootNodes = Array.from(Graph.indices(Graph.externals(graph, { direction: 'incoming' })))
+
+    if (rootNodes.length === 0) {
+      return yield* Console.log('(empty trace)')
+    }
+
+    // Apply filter to create a filtered copy of the graph
+    const filteredGraph = options.regex
+      ? filterGraphWithAncestors(graph, (nodeData, _nodeId) => {
+          const name = getSpanName(nodeData.span)
+          return options.regex!.test(name)
+        })
+      : graph
+
+    // Find root nodes in the filtered graph
+    const filteredRootNodes = Array.from(Graph.indices(Graph.externals(filteredGraph, { direction: 'incoming' })))
+
+    if (filteredRootNodes.length === 0) {
+      return yield* Console.log(options.title ? `${options.title}\n(no matches)` : '(no matches)')
+    }
+
+    const lines: string[] = []
+
+    // Add title if provided
+    if (options.title) {
+      lines.push(options.title)
+    }
+
+    // Render root nodes using the same logic as regular children
+    const rootCount = filteredRootNodes.length
+    filteredRootNodes.forEach((rootId: number, index: number) => {
+      const isLastRoot = index === rootCount - 1
+      const rootLines = renderNode(filteredGraph, rootId, '', isLastRoot)
+      lines.push(...rootLines)
+    })
+
+    return yield* Console.log(lines.join('\n'))
+  })
+
+export interface LogPerformanceTraceOptions {
+  readonly regex?: RegExp
+}
+
+/**
+ * Logs the span tree in Chrome Performance Trace Event Format.
+ * The output can be loaded in Chrome DevTools Performance tab or chrome://tracing
+ *
+ * @see https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU/preview
+ */
+export const logPerformanceTrace = (options: LogPerformanceTraceOptions = {}) =>
+  Effect.gen(function* () {
+    const maybeInfo = yield* Effect.serviceOption(DebugInfo)
+    if (Option.isNone(maybeInfo)) {
+      return yield* Console.log(
+        '(no debug info provided! To show the trace, provide the layerDebug layer in the root of your program)',
+      )
+    }
+
+    const { mutableGraph } = maybeInfo.value
+    const graph = Graph.endMutation(mutableGraph)
+
+    // Find root nodes (nodes with no incoming edges) using externals
+    const rootNodes = Array.from(Graph.indices(Graph.externals(graph, { direction: 'incoming' })))
+
+    if (rootNodes.length === 0) {
+      return yield* Console.log('[]')
+    }
+
+    // Apply filter if provided
+    const filteredGraph = options.regex
+      ? filterGraphWithAncestors(graph, (nodeData, _nodeId) => {
+          const name = getSpanName(nodeData.span)
+          return options.regex!.test(name)
+        })
+      : graph
+
+    // Find root nodes in the filtered graph
+    const filteredRootNodes = Array.from(Graph.indices(Graph.externals(filteredGraph, { direction: 'incoming' })))
+
+    // Collect all trace events
+    const events = collectTraceEvents(filteredGraph, filteredRootNodes)
+
+    // Output as compact JSON array
+    const json = JSON.stringify(events)
+    return yield* Console.log(json)
+  })
+
+export const logScopeState = ({ label }: { label: string }) =>
+  Effect.gen(function* () {
+    const scope = yield* Effect.scope
+    yield* Effect.log(`scope.state[${label}]`, (scope as any).state._tag).pipe(
+      Effect.repeat({ schedule: Schedule.fixed(Duration.millis(100)) }),
+      Effect.forkScoped,
+    )
+  })

package/src/effect/Effect.ts

@@ -1,9 +1,22 @@
 import * as OtelTracer from '@effect/opentelemetry/Tracer'
-import type { Context, Duration, Stream } from 'effect'
-import { Cause, Deferred, Effect, Fiber, FiberRef, HashSet, Logger, pipe, Scope } from 'effect'
+import {
+  Cause,
+  type Context,
+  Deferred,
+  Duration,
+  Effect,
+  Fiber,
+  FiberRef,
+  HashSet,
+  Logger,
+  pipe,
+  Scope,
+  type Stream,
+} from 'effect'
 import type { UnknownException } from 'effect/Cause'
 import { log } from 'effect/Console'
-import type { LazyArg } from 'effect/Function'
+import { dual, type LazyArg } from 'effect/Function'
+import type { Predicate, Refinement } from 'effect/Predicate'
 
 import { isPromise } from '../mod.ts'
 import { UnknownError } from './Error.ts'
@@ -94,6 +107,20 @@ export const tapCauseLogPretty = <R, E, A>(eff: Effect.Effect<A, E, R>): Effect.
     }),
   )
 
+export const ignoreIf: {
+  <E, EB extends E>(
+    refinement: Refinement<NoInfer<E>, EB>,
+  ): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<void, Exclude<E, EB>, R>
+  <E>(predicate: Predicate<NoInfer<E>>): <A, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<void, E, R>
+  <A, E, R, EB extends E>(
+    self: Effect.Effect<A, E, R>,
+    refinement: Refinement<E, EB>,
+  ): Effect.Effect<void, Exclude<E, EB>, R>
+  <A, E, R>(self: Effect.Effect<A, E, R>, predicate: Predicate<E>): Effect.Effect<void, E, R>
+} = dual(2, <A, E, R>(self: Effect.Effect<A, E, R>, predicate: Predicate<E>) =>
+  self.pipe(Effect.catchIf(predicate, () => Effect.void)),
+)
+
 export const eventListener = <TEvent = unknown>(
   target: Stream.EventListener<TEvent>,
   type: string,
@@ -166,7 +193,7 @@ export const logDuration =
       const start = Date.now()
       const res = yield* eff
       const end = Date.now()
-      yield* Effect.log(`${label}: ${end - start}ms`)
+      yield* Effect.log(`${label}: ${Duration.format(end - start)}`)
       return res
     })
 

package/src/effect/Error.ts

@@ -1,6 +1,6 @@
 import { Schema } from 'effect'
 
-export class UnknownError extends Schema.TaggedError<'UnknownError'>()('UnknownError', {
+export class UnknownError extends Schema.TaggedError<UnknownError>()('UnknownError', {
   cause: Schema.Any,
   payload: Schema.optional(Schema.Any),
 }) {}

package/src/effect/Logger.ts

@@ -8,20 +8,24 @@ const defaultDateFormat = (date: Date): string =>
     .toString()
     .padStart(2, '0')}.${date.getMilliseconds().toString().padStart(3, '0')}`
 
-export const prettyWithThread = (threadName: string) =>
+export const prettyWithThread = (threadName: string, options: { mode?: 'tty' | 'browser' } = {}) =>
   Logger.replace(
     Logger.defaultLogger,
     Logger.prettyLogger({
       formatDate: (date) => `${defaultDateFormat(date)} ${threadName}`,
+      mode: options.mode,
     }),
-    // consoleLogger(threadName),
   )
 
 export const consoleLogger = (threadName: string) =>
   Logger.make(({ message, annotations, date, logLevel, cause }) => {
+    const isCloudflareWorker = typeof navigator !== 'undefined' && navigator.userAgent === 'Cloudflare-Workers'
     const consoleFn =
       logLevel === LogLevel.Debug
-        ? console.debug
+        ? // Cloudflare Workers doesn't support console.debug 🤷
+          isCloudflareWorker
+          ? console.log
+          : console.debug
         : logLevel === LogLevel.Info
           ? console.info
           : logLevel === LogLevel.Warning
@@ -35,5 +39,11 @@ export const consoleLogger = (threadName: string) =>
       messages.push(Cause.pretty(cause, { renderErrorCause: true }))
     }
 
-    consoleFn(`[${defaultDateFormat(date)} ${threadName}]`, ...messages, annotationsObj)
+    if (Object.keys(annotationsObj).length > 0) {
+      messages.push(annotationsObj)
+    }
+
+    consoleFn(`[${defaultDateFormat(date)} ${threadName}]`, ...messages)
   })
+
+export const consoleWithThread = (threadName: string) => Logger.replace(Logger.defaultLogger, consoleLogger(threadName))

package/src/effect/OtelTracer.ts

@@ -0,0 +1,11 @@
+import { makeExternalSpan } from '@effect/opentelemetry/Tracer'
+import type { Link as OtelSpanLink } from '@opentelemetry/api'
+import type { SpanLink as EffectSpanLink } from 'effect/Tracer'
+
+export * from '@effect/opentelemetry/Tracer'
+
+export const makeSpanLink = (otelSpanLink: OtelSpanLink): EffectSpanLink => ({
+  _tag: 'SpanLink',
+  span: makeExternalSpan(otelSpanLink.context),
+  attributes: otelSpanLink.attributes ?? {},
+})