The best way to control Claude Code, Codex and more from any computer or phone

main
ts 206 lines 7.76 KB
Raw
1 /**
2 * Sink adapters for writing Effect chunks into Node writable streams.
3 *
4 * `fromWritable` creates a `Sink`, `fromWritableChannel` creates a lower-level
5 * `Channel`, and `pullIntoWritable` writes from an existing pull loop. All
6 * three adapters respect writable-stream backpressure, map writable errors with
7 * the supplied `onError` function, and can end the writable when the upstream
8 * data is done.
9 *
10 * @stability unstable
11 * @since 4.0.0
12 */
13 import type { NonEmptyReadonlyArray } from "effect/Array"
14 import * as Cause from "effect/Cause"
15 import * as Channel from "effect/Channel"
16 import * as Deferred from "effect/Deferred"
17 import * as Effect from "effect/Effect"
18 import { constVoid, identity, type LazyArg } from "effect/Function"
19 import * as Pull from "effect/Pull"
20 import * as Sink from "effect/Sink"
21 import { finished, type Writable } from "node:stream"
22 import { destroyStream } from "./internal/stream.ts"
23
24 /**
25 * Creates a `Sink` that writes chunks to a Node writable stream, respecting
26 * backpressure and mapping writable errors with `onError`. Unless `endOnDone`
27 * is `false`, the writable is ended on completion and destroyed on upstream
28 * failure or interruption.
29 *
30 * @stability unstable
31 * @category constructors
32 * @since 4.0.0
33 */
34 export const fromWritable = <E, A = Uint8Array | string>(
35 options: {
36 readonly evaluate: LazyArg<Writable | NodeJS.WritableStream>
37 readonly onError: (error: unknown) => E
38 readonly endOnDone?: boolean | undefined
39 readonly encoding?: BufferEncoding | undefined
40 }
41 ): Sink.Sink<void, A, never, E> =>
42 Sink.fromChannel(Channel.mapDone(fromWritableChannel<never, E, A>(options), (_) => [_]))
43
44 /**
45 * Creates a `Channel` that pulls chunks from upstream and writes them to a
46 * Node writable stream, respecting backpressure. Unless `endOnDone` is
47 * `false`, the writable is ended when upstream is done and destroyed on
48 * upstream failure or interruption.
49 *
50 * @stability unstable
51 * @category constructors
52 * @since 4.0.0
53 */
54 export const fromWritableChannel = <IE, E, A = Uint8Array | string>(
55 options: {
56 readonly evaluate: LazyArg<Writable | NodeJS.WritableStream>
57 readonly onError: (error: unknown) => E
58 readonly endOnDone?: boolean | undefined
59 readonly encoding?: BufferEncoding | undefined
60 }
61 ): Channel.Channel<never, IE | E, void, NonEmptyReadonlyArray<A>, IE> =>
62 Channel.fromTransform((pull: Pull.Pull<NonEmptyReadonlyArray<A>, IE, unknown>) => {
63 const writable = options.evaluate() as Writable
64 const write = pullIntoWritable({ ...options, writable, pull })
65 return Effect.succeed(
66 options.endOnDone === false
67 ? write
68 : Effect.onError(write, (cause) => Pull.isDoneCause(cause) ? Effect.void : releaseWritable(writable))
69 )
70 })
71
72 // Destroy the writable and wait for destruction to settle, keeping any
73 // destruction error handled.
74 const releaseWritable = (writable: Writable): Effect.Effect<void> =>
75 Effect.callback<void>((resume) => {
76 const onDestroyed = () => resume(Effect.void)
77 if (writable.closed) {
78 // Destruction may be complete with its error still queued.
79 const cleanup = finished(writable, { readable: false }, () => {
80 cleanup()
81 onDestroyed()
82 })
83 } else {
84 destroyStream(writable, constVoid, onDestroyed)
85 }
86 })
87
88 /**
89 * Writes Effect chunks into a Node writable stream.
90 *
91 * **When to use**
92 *
93 * Use to implement custom Node stream adapters that already have an upstream
94 * pull and need direct control over a writable stream.
95 *
96 * **Details**
97 *
98 * The loop waits for `drain` when needed, fails on writable errors, and ends
99 * the writable on upstream completion unless `endOnDone` is `false`.
100 *
101 * @stability unstable
102 * @category converting
103 * @since 4.0.0
104 */
105 export const pullIntoWritable = <A, IE, E>(options: {
106 readonly pull: Pull.Pull<NonEmptyReadonlyArray<A>, IE, unknown>
107 readonly writable: Writable
108 readonly onError: (error: unknown) => E
109 readonly endOnDone?: boolean | undefined
110 readonly encoding?: BufferEncoding | undefined
111 }): Pull.Pull<never, IE | E, unknown> =>
112 Effect.withFiber((fiber) => {
113 const dispatcher = fiber.currentDispatcher
114 const completion = Deferred.makeUnsafe<void>()
115 const failure = Deferred.makeUnsafe<never, E>()
116 const onError = (error: unknown) => Deferred.doneUnsafe(failure, Effect.failSync(() => options.onError(error)))
117 let errorEmitted = false
118 const onStreamError = (error: unknown) => {
119 errorEmitted = true
120 onError(error)
121 }
122 // finished() only reports once, so keep listening for errors from writes
123 // made after the writable has finished.
124 options.writable.on("error", onStreamError)
125 const cleanup = finished(options.writable, { readable: false }, (error) => {
126 if (error) {
127 onError(error)
128 } else {
129 Deferred.doneUnsafe(completion, Effect.void)
130 }
131 })
132 return options.pull.pipe(
133 Effect.flatMap((chunk) => {
134 let i = 0
135 return Effect.callback<void, E>((resume) => {
136 let cancelled = false
137 // Let Node finish auto-destruction before attempting another write.
138 const onFinish = () => dispatcher.scheduleTask(loop, 0)
139 const loop = () => {
140 options.writable.off("drain", loop)
141 options.writable.off("finish", onFinish)
142 for (; i < chunk.length;) {
143 if (cancelled) {
144 return
145 }
146 const success = options.writable.write(chunk[i++], options.encoding as any, (error) => {
147 if (!error) return
148 if (options.writable.closed) {
149 // Closed streams can reject writes through the callback only;
150 // there is no pending destruction to wait for.
151 onError(error)
152 } else {
153 // Let Node initiate auto-destruction before failure cleanup
154 // checks whether an error event is still pending.
155 dispatcher.scheduleTask(() => onError(error), 0)
156 }
157 })
158 if (!success) {
159 if (!cancelled) {
160 options.writable.once("drain", loop)
161 // A normally finished writable will never emit drain. Resume
162 // the loop so any remaining writes can report their errors.
163 options.writable.once("finish", onFinish)
164 }
165 return
166 }
167 }
168 if (!cancelled) {
169 resume(Effect.void)
170 }
171 }
172 loop()
173 return Effect.sync(() => {
174 cancelled = true
175 options.writable.off("drain", loop)
176 options.writable.off("finish", onFinish)
177 })
178 })
179 }),
180 Effect.forever({ disableYield: true }),
181 options.endOnDone !== false ?
182 Pull.catchDone((_) => {
183 options.writable.end()
184 return Effect.andThen(Deferred.await(completion), Cause.done(_))
185 }) :
186 identity,
187 Effect.raceFirst(Deferred.await(failure)),
188 Effect.ensuring(Effect.sync(() => {
189 cleanup()
190 const removeErrorListener = () => {
191 options.writable.off("error", onStreamError)
192 options.writable.off("error", removeErrorListener)
193 options.writable.off("close", removeErrorListener)
194 }
195 if (options.writable.errored && !options.writable.closed && !errorEmitted) {
196 // A write callback can fail before asynchronous _destroy completes.
197 // Keep handling Node's pending error until it is emitted (or closed),
198 // without delaying failure for callback-only errors on closed streams.
199 options.writable.once("error", removeErrorListener)
200 options.writable.once("close", removeErrorListener)
201 } else {
202 removeErrorListener()
203 }
204 }))
205 )
206 })