Mirror of https://github.com/roostorg/coop
github.com/roostorg/coop
1import type SafeTracer from '../../utils/SafeTracer.js';
2import type {
3 CDCChange,
4 CDCConfig,
5} from '../../storage/dataWarehouse/IDataWarehouseAnalytics.js';
6import type {
7 AnalyticsEventInput,
8 AnalyticsQueryResult,
9 AnalyticsWriteOptions,
10} from './types.js';
11
12/**
13 * Contract implemented by every analytics adapter.
14 *
15 * Adapters are free to batch, buffer, or stream writes however they like.
16 * The core application will await each call; adapters should ensure the
17 * returned promise resolves once the data is durable (or appropriately queued)
18 * according to their guarantees.
19 */
20export interface IAnalyticsAdapter {
21 /** Human friendly provider name for logging / diagnostics. */
22 readonly name: string;
23
24 /**
25 * Write analytics events to a logical table.
26 *
27 * @param table - Logical table identifier (e.g. 'RULE_EXECUTIONS').
28 * @param events - Rows to persist. Adapters may mutate or enrich rows before
29 * persistence, but should NOT mutate the original array.
30 */
31 writeEvents(
32 table: string,
33 events: readonly AnalyticsEventInput[],
34 options?: AnalyticsWriteOptions,
35 ): Promise<void>;
36
37 /**
38 * Execute an analytics query. Most adapters will translate the SQL string
39 * into their native dialect before execution.
40 */
41 query<T = AnalyticsQueryResult>(
42 sql: string,
43 params?: readonly unknown[],
44 ): Promise<readonly T[]>;
45
46 /** Flush any in-memory buffers. Called during graceful shutdown. */
47 flush(): Promise<void>;
48
49 /** Release external resources (connections, clients, etc.). */
50 close(): Promise<void>;
51
52 /** Optional support for change data capture streams. */
53 createCDCStream?<TableName extends string>(
54 config: CDCConfig<TableName>,
55 ): Promise<void>;
56
57 consumeCDCChanges?<T = unknown>(
58 streamName: string,
59 callback: (changes: CDCChange<T>[]) => Promise<void>,
60 tracer?: SafeTracer,
61 ): Promise<void>;
62
63 supportsCDC?(): boolean;
64}