sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ S3/ BucketEventSource.ts

import * as Binding from "alchemy/Binding";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Bucket } from "./Bucket.ts";
import type { BucketNotification, NotificationsProps } from "./BucketNotifications.ts";
import type { S3EventType } from "./S3Event.ts";

/**
 * Event source that streams a bucket's notifications (object created, object
 * removed, ...) into the host Lambda Function. Usually consumed through the
 * `consumeBucketEvents` helper, which provisions the bucket-notification
 * subscription at deploy time and registers the stream handler at runtime.
 * Provide the implementation with `Effect.provide(Lambda.BucketEventSource)`.
 * ### Consuming Bucket Events
 * **Example:** Process Object-Created Events
 * ```typescript
 * export default MyFunction.make(
 *   { main: import.meta.url },
 *   Effect.gen(function* () {
 *     const bucket = yield* AWS.S3.Bucket("UploadsBucket");
 *     const putObject = yield* AWS.S3.PutObject(bucket);
 *
 *     // filter to `incoming/` so the derived `processed/` write does not
 *     // re-trigger the subscription
 *     yield* AWS.S3.consumeBucketEvents(
 *       bucket,
 *       { events: ["s3:ObjectCreated:*"], prefix: "incoming/" },
 *       (stream) =>
 *         stream.pipe(
 *           Stream.runForEach((event) =>
 *             putObject({
 *               Key: `processed/${event.key.slice("incoming/".length)}`,
 *               Body: JSON.stringify({ key: event.key, size: event.size }),
 *             }).pipe(Effect.orDie),
 *           ),
 *         ),
 *     );
 *
 *     return {
 *       fetch: Effect.succeed(HttpServerResponse.text("ok")),
 *     };
 *   }).pipe(
 *     Effect.provide(
 *       Layer.mergeAll(Lambda.BucketEventSource, AWS.S3.PutObjectHttp),
 *     ),
 *   ),
 * );
 * ```
 *
 * ### Reading the Event's Object Version
 * **Example:** Read the version that triggered a creation event
 * ```typescript
 * const getObject = yield* AWS.S3.GetObject(bucket);
 * yield* AWS.S3.consumeBucketEvents(
 *   bucket,
 *   { events: ["s3:ObjectCreated:*"], prefix: "incoming/" },
 *   (events) => events.pipe(
 *     Stream.runForEach((event) =>
 *       getObject({ Key: event.key, VersionId: event.versionId }).pipe(
 *         Effect.flatMap(({ Body }) => Stream.runDrain(Body!)),
 *         Effect.orDie,
 *       ),
 *     ),
 *   ),
 * );
 * // Provide Lambda.BucketEventSource and AWS.S3.GetObjectHttp on the function.
 * ```
 *
 * Passing `event.versionId` reads the triggering data version even if the key
 * has since been overwritten. Unversioned events omit it and read the current
 * object. Removal events can identify a delete marker or an already-deleted
 * version; they may omit `size` and `eTag` and are not object-read signals.
 * `sequencer`, when present, orders events only for the same object key.
 *
 * @binding
 */
export interface BucketEventSource extends Binding.Service<
  BucketEventSource,
  "BucketNotificationStream",
  BucketEventSourceService
> {}

export const BucketEventSource = Binding.Service<BucketEventSource>("BucketNotificationStream");

export type BucketEventSourceService = <
  Events extends S3EventType[],
  StreamReq = never,
  Req = never,
>(
  bucket: Bucket,
  props: NotificationsProps<Events>,
  process: (
    stream: Stream.Stream<BucketNotification, never, StreamReq>,
  ) => Effect.Effect<void, never, Req>,
) => Effect.Effect<void, never, never>;