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

main
ts 85 lines 3.06 KB
Raw
1 import * as Binding from "alchemy/Binding";
2 import type { RuntimeContext } from "alchemy/RuntimeContext";
3 import type * as Effect from "effect/Effect";
4 import type { EncodedRecord, K2SchemaError, ProduceError } from "./K2Types.ts";
5 import type { Stream, StreamRecord } from "./Stream.ts";
6
7 /**
8 * Binding service that turns a K2 {@link Stream} into a typed
9 * {@link WriteStreamClient} you can call from a Worker's (or any host's)
10 * runtime Effect.
11 *
12 * `send` appends a batch of records atomically: all of them are stored, or
13 * none. A batch can be at most 5 MB and each record at most 1 MB.
14 * ### Sending Records
15 * **Example:** Producer route
16 * ```typescript
17 * const orders = yield* Cloudflare.K2.WriteStream(Orders);
18 *
19 * return {
20 * fetch: Effect.gen(function* () {
21 * yield* orders.send([
22 * { content: JSON.stringify({ id: 1 }), headers: { source: "api" } },
23 * { content: new Uint8Array([1, 2, 3]) },
24 * ]);
25 * return HttpServerResponse.empty({ status: 202 });
26 * }),
27 * };
28 * ```
29 *
30 * ### Typed Records
31 * **Example:** Send values of the stream's schema
32 * ```typescript
33 * const Order = Schema.Struct({ id: Schema.Number, total: Schema.Number });
34 * const Orders = Cloudflare.K2.Stream("Orders", { schema: Order });
35 *
36 * const orders = yield* Cloudflare.K2.WriteStream(Orders);
37 * // JSON-encoded, sent with `content-type: application/json`
38 * yield* orders.send([{ id: 1, total: 42 }]);
39 * ```
40 *
41 * ### Handling Errors
42 * **Example:** Retry only when the batch was not stored
43 * ```typescript
44 * yield* orders.send(records).pipe(
45 * // K2Unavailable: the batch was NOT stored. Never retry
46 * // K2AppendOutcomeUnknown — the batch may have been stored.
47 * Effect.retry({
48 * while: (e) => e._tag === "K2Unavailable",
49 * times: 3,
50 * }),
51 * );
52 * ```
53 *
54 * Provide {@link WriteStreamBinding} (native `k2` Worker binding),
55 * {@link WriteStreamHttp} (scoped `K2 Produce` token over the stream's HTTP
56 * input) or {@link WriteStreamLocal} (current credentials, for Actions).
57 *
58 * @binding
59 * @product K2
60 * @category Storage & Databases
61 */
62 export interface WriteStream extends Binding.Service<
63 WriteStream,
64 "Cloudflare.K2.WriteStream",
65 (stream: Stream<any>) => Effect.Effect<WriteStreamClient<any>>
66 > {
67 <A>(stream: Stream<A>): Effect.Effect<WriteStreamClient<StreamRecord<A>>, never, WriteStream>;
68 }
69
70 export const WriteStream = Binding.Service<WriteStream>("Cloudflare.K2.WriteStream");
71
72 /**
73 * Producer client for a K2 stream. `A` is the stream's schema type, or raw
74 * bytes plus headers (`Cloudflare.K2.Record`) for a stream without one.
75 */
76 export interface WriteStreamClient<A> {
77 /** Append a batch of records atomically. */
78 send(records: ReadonlyArray<A>): Effect.Effect<void, ProduceError, RuntimeContext>;
79 /** Encode values into the bytes + headers shape `sendEncoded` accepts. */
80 encode(records: ReadonlyArray<A>): Effect.Effect<ReadonlyArray<EncodedRecord>, K2SchemaError>;
81 /** Append already-encoded records atomically. */
82 sendEncoded(
83 records: ReadonlyArray<EncodedRecord>,
84 ): Effect.Effect<void, ProduceError, RuntimeContext>;
85 }