1/**
2 * High-level layers for connecting an Effect runtime to the unstable devtools
3 * tracer.
4 *
5 * `DevTools` is the application-facing entry point for installing a tracer that
6 * mirrors the current tracer and streams spans, span events, span completions,
7 * and metric snapshots to an external devtools process. Lower-level socket
8 * protocol details live in `DevToolsClient`.
9 *
10 * @stability unstable
11 * @since 4.0.0
12 */
13import * as Layer from "../Layer.ts"
14import * as Socket from "../socket/Socket.ts"
15import * as DevToolsClient from "./DevToolsClient.ts"
16
17/**
18 * Layer that installs the devtools tracer using an existing `Socket`.
19 *
20 * @stability unstable
21 * @category layers
22 * @since 4.0.0
23 */
24export const layerSocket: Layer.Layer<never, never, Socket.Socket> = DevToolsClient.layerTracer
25
26/**
27 * Layer that installs the devtools tracer over a WebSocket connection to the
28 * specified URL, defaulting to `ws://localhost:34437`.
29 *
30 * @stability unstable
31 * @category layers
32 * @since 4.0.0
33 */
34export const layerWebSocket = (
35 url = "ws://localhost:34437"
36): Layer.Layer<never, never, Socket.WebSocketConstructor> =>
37 DevToolsClient.layerTracer.pipe(
38 Layer.provide(Socket.layerWebSocket(url))
39 )
40
41/**
42 * Layer that installs the devtools tracer over a WebSocket connection using the
43 * global WebSocket constructor, defaulting to `ws://localhost:34437`.
44 *
45 * **When to use**
46 *
47 * Use to stream Effect tracing and metrics telemetry to a devtools process when
48 * the runtime environment already provides a global `WebSocket` constructor.
49 *
50 * **Details**
51 *
52 * This is a convenience wrapper around `layerWebSocket(url)` that provides
53 * `Socket.layerWebSocketConstructorGlobal`, so the resulting layer has no
54 * remaining requirements.
55 *
56 * **Gotchas**
57 *
58 * This layer only installs the client-side tracer; it does not start a devtools
59 * server, so the configured WebSocket endpoint must already be reachable. It
60 * relies on `globalThis.WebSocket` being available in the runtime.
61 *
62 * @see {@link layerWebSocket} for installing the devtools tracer with an explicit `WebSocketConstructor` requirement
63 * @see {@link layerSocket} for installing the devtools tracer over an existing `Socket` transport
64 *
65 * @stability unstable
66 * @category layers
67 * @since 4.0.0
68 */
69export const layer = (url = "ws://localhost:34437"): Layer.Layer<never> =>
70 layerWebSocket(url).pipe(
71 Layer.provide(Socket.layerWebSocketConstructorGlobal)
72 )