sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ K2/ WriteStream.ts

import * as Binding from "alchemy/Binding";
import type { RuntimeContext } from "alchemy/RuntimeContext";
import type * as Effect from "effect/Effect";
import type { EncodedRecord, K2SchemaError, ProduceError } from "./K2Types.ts";
import type { Stream, StreamRecord } from "./Stream.ts";

/**
 * Binding service that turns a K2 {@link Stream} into a typed
 * {@link WriteStreamClient} you can call from a Worker's (or any host's)
 * runtime Effect.
 *
 * `send` appends a batch of records atomically: all of them are stored, or
 * none. A batch can be at most 5 MB and each record at most 1 MB.
 * ### Sending Records
 * **Example:** Producer route
 * ```typescript
 * const orders = yield* Cloudflare.K2.WriteStream(Orders);
 *
 * return {
 *   fetch: Effect.gen(function* () {
 *     yield* orders.send([
 *       { content: JSON.stringify({ id: 1 }), headers: { source: "api" } },
 *       { content: new Uint8Array([1, 2, 3]) },
 *     ]);
 *     return HttpServerResponse.empty({ status: 202 });
 *   }),
 * };
 * ```
 *
 * ### Typed Records
 * **Example:** Send values of the stream's schema
 * ```typescript
 * const Order = Schema.Struct({ id: Schema.Number, total: Schema.Number });
 * const Orders = Cloudflare.K2.Stream("Orders", { schema: Order });
 *
 * const orders = yield* Cloudflare.K2.WriteStream(Orders);
 * // JSON-encoded, sent with `content-type: application/json`
 * yield* orders.send([{ id: 1, total: 42 }]);
 * ```
 *
 * ### Handling Errors
 * **Example:** Retry only when the batch was not stored
 * ```typescript
 * yield* orders.send(records).pipe(
 *   // K2Unavailable: the batch was NOT stored. Never retry
 *   // K2AppendOutcomeUnknown — the batch may have been stored.
 *   Effect.retry({
 *     while: (e) => e._tag === "K2Unavailable",
 *     times: 3,
 *   }),
 * );
 * ```
 *
 * Provide {@link WriteStreamBinding} (native `k2` Worker binding),
 * {@link WriteStreamHttp} (scoped `K2 Produce` token over the stream's HTTP
 * input) or {@link WriteStreamLocal} (current credentials, for Actions).
 *
 * @binding
 * @product K2
 * @category Storage & Databases
 */
export interface WriteStream extends Binding.Service<
  WriteStream,
  "Cloudflare.K2.WriteStream",
  (stream: Stream<any>) => Effect.Effect<WriteStreamClient<any>>
> {
  <A>(stream: Stream<A>): Effect.Effect<WriteStreamClient<StreamRecord<A>>, never, WriteStream>;
}

export const WriteStream = Binding.Service<WriteStream>("Cloudflare.K2.WriteStream");

/**
 * Producer client for a K2 stream. `A` is the stream's schema type, or raw
 * bytes plus headers (`Cloudflare.K2.Record`) for a stream without one.
 */
export interface WriteStreamClient<A> {
  /** Append a batch of records atomically. */
  send(records: ReadonlyArray<A>): Effect.Effect<void, ProduceError, RuntimeContext>;
  /** Encode values into the bytes + headers shape `sendEncoded` accepts. */
  encode(records: ReadonlyArray<A>): Effect.Effect<ReadonlyArray<EncodedRecord>, K2SchemaError>;
  /** Append already-encoded records atomically. */
  sendEncoded(
    records: ReadonlyArray<EncodedRecord>,
  ): Effect.Effect<void, ProduceError, RuntimeContext>;
}