1import type * as keyspacesstreams from "@distilled.cloud/aws/keyspacesstreams";
2import type * as Effect from "effect/Effect";
3import * as Binding from "../../Binding.ts";
4import type { Table } from "./Table.ts";
5
6export interface ListTableStreamsRequest extends Omit<
7 keyspacesstreams.ListStreamsInput,
8 "keyspaceName" | "tableName"
9> {}
10
11/**
12 * The typed client returned by binding {@link TableStreams} to a `Table`.
13 * `listStreams` automatically injects the table's keyspace and table name;
14 * the remaining operations traverse a stream by ARN / shard iterator
15 * obtained from prior calls.
16 */
17export interface TableStreamsClient {
18 /**
19 * List the CDC streams of the bound table (the stream with the greatest
20 * `streamLabel` is the current one — also exposed as the table's
21 * `latestStreamArn` attribute).
22 */
23 listStreams: (
24 request?: ListTableStreamsRequest,
25 ) => Effect.Effect<
26 keyspacesstreams.ListStreamsOutput,
27 keyspacesstreams.ListStreamsError
28 >;
29 /**
30 * Describe a stream: status, view type, retention, and shard composition.
31 */
32 getStream: (
33 request: keyspacesstreams.GetStreamInput,
34 ) => Effect.Effect<
35 keyspacesstreams.GetStreamOutput,
36 keyspacesstreams.GetStreamError
37 >;
38 /**
39 * Obtain an iterator positioned in a shard (`TRIM_HORIZON`, `LATEST`,
40 * `AT_SEQUENCE_NUMBER`, or `AFTER_SEQUENCE_NUMBER`).
41 */
42 getShardIterator: (
43 request: keyspacesstreams.GetShardIteratorInput,
44 ) => Effect.Effect<
45 keyspacesstreams.GetShardIteratorOutput,
46 keyspacesstreams.GetShardIteratorError
47 >;
48 /**
49 * Read change records from a shard iterator.
50 */
51 getRecords: (
52 request: keyspacesstreams.GetRecordsInput,
53 ) => Effect.Effect<
54 keyspacesstreams.GetRecordsOutput,
55 keyspacesstreams.GetRecordsError
56 >;
57}
58
59/**
60 * Runtime binding for the Amazon Keyspaces CDC streams data-plane API
61 * (`cassandra:ListStreams` / `GetStream` / `GetShardIterator` /
62 * `GetRecords`).
63 *
64 * Bind this to a `Table` whose `cdcSpecification` is enabled to get a typed
65 * client for traversing the table's change-data-capture stream.
66 * ### Reading Change Data
67 * **Example:** Traverse the Latest Stream
68 * ```typescript
69 * const streams = yield* AWS.Keyspaces.TableStreams(table);
70 *
71 * const { streams: available } = yield* streams.listStreams();
72 * const streamArn = available![0].streamArn;
73 *
74 * const stream = yield* streams.getStream({ streamArn });
75 * const { shardIterator } = yield* streams.getShardIterator({
76 * streamArn,
77 * shardId: stream.shards![0].shardId!,
78 * shardIteratorType: "TRIM_HORIZON",
79 * });
80 *
81 * const { changeRecords } = yield* streams.getRecords({
82 * shardIterator: shardIterator!,
83 * });
84 * ```
85 *
86 * @binding
87 */
88export interface TableStreams extends Binding.Service<
89 TableStreams,
90 "AWS.Keyspaces.TableStreams",
91 <T extends Table>(table: T) => Effect.Effect<TableStreamsClient>
92> {}
93export const TableStreams = Binding.Service<TableStreams>(
94 "AWS.Keyspaces.TableStreams",
95);