The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 04:45 UTC
| 1 | import type * as DynamoDB from "@distilled.cloud/aws/dynamodb"; |
| 2 | import * as Binding from "alchemy/Binding"; |
| 3 | import type * as lambda from "aws-lambda"; |
| 4 | import type * as Duration from "effect/Duration"; |
| 5 | import * as Effect from "effect/Effect"; |
| 6 | import type { Table, TableEvent, TableRecord } from "./Table.ts"; |
| 7 | |
| 8 | export type StreamRecord<Data> = TableRecord<Data>; |
| 9 | |
| 10 | export type StreamEvent<Data> = TableEvent<Data>; |
| 11 | |
| 12 | /** |
| 13 | * Lambda's partial-batch response for DynamoDB Streams. Report the |
| 14 | * `SequenceNumber` of the first record that failed as `itemIdentifier`; |
| 15 | * Lambda checkpoints before it and retries from there. |
| 16 | */ |
| 17 | export type DynamoDBBatchResponse = import("aws-lambda").DynamoDBBatchResponse; |
| 18 | |
| 19 | /** |
| 20 | * Handler for one delivered batch of table changes: receives the |
| 21 | * {@link StreamEvent} and returns Lambda's {@link DynamoDBBatchResponse} (or |
| 22 | * `void` when every record succeeded). A failure or defect retries the whole |
| 23 | * batch. |
| 24 | * |
| 25 | * Row images default to raw attribute values; annotate the parameter |
| 26 | * (`event: DynamoDB.StreamEvent<Order>`) to type them. The method form keeps |
| 27 | * the parameter bivariant so an annotated handler is accepted. |
| 28 | */ |
| 29 | export type TableChangesHandler<E = never, Req = never> = { |
| 30 | handle( |
| 31 | event: StreamEvent<Record<string, lambda.AttributeValue>>, |
| 32 | ): Effect.Effect<DynamoDBBatchResponse | void, E, Req>; |
| 33 | }["handle"]; |
| 34 | |
| 35 | /** |
| 36 | * Event source binding that subscribes a Lambda function to a DynamoDB |
| 37 | * table's change stream. Enables the stream on the table (via the binding |
| 38 | * contract) and creates the Lambda event source mapping. |
| 39 | * |
| 40 | * Prefer the {@link consumeTableChanges} helper for ergonomic use; provide |
| 41 | * the runtime-specific implementation layer (e.g. `Lambda.TableEventSource`) |
| 42 | * on the Function. |
| 43 | * |
| 44 | * @binding |
| 45 | */ |
| 46 | export interface TableEventSource extends Binding.Service< |
| 47 | TableEventSource, |
| 48 | "AWS.DynamoDB.TableEventSource", |
| 49 | TableEventSourceService |
| 50 | > {} |
| 51 | export const TableEventSource = Binding.Service<TableEventSource>("AWS.DynamoDB.TableEventSource"); |
| 52 | |
| 53 | export type TableEventSourceService = <E = never, Req = never>( |
| 54 | table: Table, |
| 55 | props: StreamsProps, |
| 56 | process: TableChangesHandler<E, Req>, |
| 57 | ) => Effect.Effect<void, never, never>; |
| 58 | |
| 59 | export interface TableEventSourceProps { |
| 60 | /** |
| 61 | * The maximum number of records in each batch that Lambda pulls from the stream. |
| 62 | * @default 100 |
| 63 | */ |
| 64 | batchSize?: number; |
| 65 | /** |
| 66 | * The maximum amount of time that Lambda spends gathering records before |
| 67 | * invoking the function, e.g. `"5 seconds"` or `Duration.seconds(5)`. |
| 68 | * Rounded to whole seconds on the wire. |
| 69 | * @default 0 |
| 70 | */ |
| 71 | maximumBatchingWindow?: Duration.Input; |
| 72 | /** |
| 73 | * The position in the stream from which to start reading. |
| 74 | * @default "LATEST" |
| 75 | */ |
| 76 | startingPosition?: "TRIM_HORIZON" | "LATEST" | "AT_TIMESTAMP"; |
| 77 | /** |
| 78 | * The timestamp to start reading from when `startingPosition` is `AT_TIMESTAMP`. |
| 79 | */ |
| 80 | startingPositionTimestamp?: Date; |
| 81 | /** |
| 82 | * The number of batches to process from each shard concurrently. |
| 83 | * @default 1 |
| 84 | */ |
| 85 | parallelizationFactor?: number; |
| 86 | /** |
| 87 | * Split the batch in two and retry if the function returns an error. |
| 88 | * @default false |
| 89 | */ |
| 90 | bisectBatchOnFunctionError?: boolean; |
| 91 | /** |
| 92 | * Discard records older than the specified age, e.g. `"1 hour"` or |
| 93 | * `Duration.hours(1)`. Rounded to whole seconds on the wire. Omit to never |
| 94 | * discard records by age. |
| 95 | */ |
| 96 | maximumRecordAge?: Duration.Input; |
| 97 | /** |
| 98 | * Discard records after the specified number of retries. |
| 99 | * @default -1 |
| 100 | */ |
| 101 | maximumRetryAttempts?: number; |
| 102 | /** |
| 103 | * The duration of a processing window for tumbling windows, e.g. |
| 104 | * `"30 seconds"` or `Duration.seconds(30)`. Rounded to whole seconds on |
| 105 | * the wire (0–900 seconds). |
| 106 | */ |
| 107 | tumblingWindow?: Duration.Input; |
| 108 | } |
| 109 | |
| 110 | export interface StreamsProps extends TableEventSourceProps { |
| 111 | /** |
| 112 | * The DynamoDB stream view type to enable on the table. |
| 113 | * @default "NEW_AND_OLD_IMAGES" |
| 114 | */ |
| 115 | streamViewType?: DynamoDB.StreamViewType; |
| 116 | } |
| 117 | |
| 118 | /** |
| 119 | * Consume change data capture events from a DynamoDB table via a Lambda |
| 120 | * event source mapping. The stream is enabled automatically through the |
| 121 | * binding contract. |
| 122 | * |
| 123 | * The handler receives each delivered {@link StreamEvent} (only the records |
| 124 | * from `table`) and returns Lambda's {@link DynamoDBBatchResponse}: name the |
| 125 | * first failed record's `SequenceNumber` to checkpoint before it, or return |
| 126 | * `void` when every record succeeded. If the handler fails, the whole batch is |
| 127 | * retried. |
| 128 | * |
| 129 | * Each batch runs inside a `process <table>` span (`SpanKind.CONSUMER`). |
| 130 | * |
| 131 | * Provide `Lambda.TableEventSource` on the Function to satisfy the binding. |
| 132 | * |
| 133 | * @example Log every table change |
| 134 | * ```typescript |
| 135 | * yield* DynamoDB.consumeTableChanges( |
| 136 | * table, |
| 137 | * { streamViewType: "NEW_AND_OLD_IMAGES", startingPosition: "TRIM_HORIZON" }, |
| 138 | * Effect.fn(function* (event) { |
| 139 | * for (const record of event.Records) { |
| 140 | * yield* Effect.log(`${record.eventName}: ${JSON.stringify(record.dynamodb.Keys)}`); |
| 141 | * } |
| 142 | * }), |
| 143 | * ); |
| 144 | * ``` |
| 145 | * |
| 146 | * @example Type the row images |
| 147 | * ```typescript |
| 148 | * interface Order { |
| 149 | * id: { S: string }; |
| 150 | * status: { S: string }; |
| 151 | * } |
| 152 | * |
| 153 | * yield* DynamoDB.consumeTableChanges( |
| 154 | * table, |
| 155 | * { streamViewType: "NEW_IMAGE" }, |
| 156 | * Effect.fn(function* (event: DynamoDB.StreamEvent<Order>) { |
| 157 | * for (const record of event.Records) { |
| 158 | * yield* Effect.log(record.dynamodb.NewImage?.status.S); |
| 159 | * } |
| 160 | * }), |
| 161 | * ); |
| 162 | * ``` |
| 163 | * |
| 164 | * @example Checkpoint at the first failed record |
| 165 | * ```typescript |
| 166 | * const sendMessage = yield* AWS.SQS.SendMessage(queue); |
| 167 | * |
| 168 | * yield* DynamoDB.consumeTableChanges( |
| 169 | * table, |
| 170 | * { streamViewType: "NEW_AND_OLD_IMAGES", batchSize: 10 }, |
| 171 | * Effect.fn(function* (event) { |
| 172 | * for (const record of event.Records) { |
| 173 | * const ok = yield* sendMessage({ |
| 174 | * MessageBody: JSON.stringify({ |
| 175 | * eventName: record.eventName, |
| 176 | * keys: record.dynamodb.Keys, |
| 177 | * newImage: record.dynamodb.NewImage, |
| 178 | * }), |
| 179 | * }).pipe( |
| 180 | * Effect.as(true), |
| 181 | * Effect.catchCause(() => Effect.succeed(false)), |
| 182 | * ); |
| 183 | * if (!ok) { |
| 184 | * return { batchItemFailures: [{ itemIdentifier: record.dynamodb.SequenceNumber! }] }; |
| 185 | * } |
| 186 | * } |
| 187 | * }), |
| 188 | * ); |
| 189 | * ``` |
| 190 | */ |
| 191 | export const consumeTableChanges = <E = never, Req = never>( |
| 192 | table: Table, |
| 193 | props: StreamsProps = {}, |
| 194 | handler: TableChangesHandler<E, Req>, |
| 195 | ) => TableEventSource.use((source) => source(table, props, handler)); |