@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
ts 195 lines 6.36 KB
Raw
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));