@adonis-agora/flags 0.0.0-stage → 0.1.0

package/dist/src/analytics/clickhouse_backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickhouse_backend.d.ts","sourceRoot":"","sources":["../../../src/analytics/clickhouse_backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAE,KAAK,gBAAgB,EAAgB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,KAAK,gBAAgB,EAAqB,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEjG;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,gBAAgB;;IACxD,QAAQ,CAAC,IAAI,gBAAgB;IAC7B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAElC,YAAY,OAAO,EAAE,iBAAiB,EAErC;IAUK,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAMxF;IAEK,MAAM,CACV,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,gBAAgB,EAC5B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAwB7C;CACF"}

package/dist/src/analytics/clickhouse_backend.js

@@ -0,0 +1,48 @@
+import { ClickHouseClient } from '../sinks/clickhouse.js';
+import { statsFromRow } from './backend.js';
+import { subjectAggregates } from './metrics.js';
+/**
+ * Level 3 of DESIGN §12: reads the table the `clickhouse` sink writes. Queries use `FINAL` so
+ * re-sent events are collapsed even before ClickHouse merges them.
+ */
+export class ClickHouseBackend {
+    kind = 'clickhouse';
+    client;
+    constructor(options) {
+        this.client = new ClickHouseClient(options);
+    }
+    #exposuresSql() {
+        return `SELECT subject, argMin(variant, ts) AS variant, min(ts) AS first_seen_ts
+              FROM ${this.client.table} FINAL
+             WHERE type = 'exposure' AND environment = {environment:String}
+               AND experiment = {experiment:String}
+             GROUP BY subject`;
+    }
+    async exposures(experiment, environment) {
+        const rows = await this.client.select(`SELECT variant, count() AS n FROM (${this.#exposuresSql()}) GROUP BY variant`, { experiment, environment });
+        return Object.fromEntries(rows.map((row) => [row.variant, Number(row.n)]));
+    }
+    async metric(experiment, definition, environment) {
+        const { post, pre } = subjectAggregates(definition);
+        const rows = await this.client.select(`WITH x AS (${this.#exposuresSql()}),
+            t AS (
+              SELECT subject, value, ts FROM ${this.client.table} FINAL
+               WHERE type = 'track' AND environment = {environment:String}
+                 AND name = {event:String}
+            )
+       SELECT variant, count() AS n,
+              sum(y) AS sum_y, sum(y * y) AS sum_y2,
+              sum(xv) AS sum_x, sum(xv * xv) AS sum_x2, sum(xv * y) AS sum_xy
+         FROM (
+           SELECT x.variant AS variant, x.subject AS subject,
+                  toFloat64(${post}) AS y,
+                  toFloat64(${pre}) AS xv
+             FROM x
+             LEFT JOIN t ON t.subject = x.subject
+            GROUP BY x.variant, x.subject
+         )
+        GROUP BY variant`, { experiment, environment, event: definition.event });
+        return Object.fromEntries(rows.map((row) => [String(row.variant), statsFromRow(row)]));
+    }
+}
+//# sourceMappingURL=clickhouse_backend.js.map

package/dist/src/analytics/clickhouse_backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clickhouse_backend.js","sourceRoot":"","sources":["../../../src/analytics/clickhouse_backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAA0B,MAAM,wBAAwB,CAAC;AAClF,OAAO,EAAyB,YAAY,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAyB,iBAAiB,EAA2B,MAAM,cAAc,CAAC;AAEjG;;;GAGG;AACH,MAAM,OAAO,iBAAiB;IACnB,IAAI,GAAG,YAAY,CAAC;IACpB,MAAM,CAAmB;IAElC,YAAY,OAA0B;QACpC,IAAI,CAAC,MAAM,GAAG,IAAI,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,aAAa;QACX,OAAO;qBACU,IAAI,CAAC,MAAM,CAAC,KAAK;;;8BAGR,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,UAAkB,EAAE,WAAmB;QACrD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CACnC,sCAAsC,IAAI,CAAC,aAAa,EAAE,oBAAoB,EAC9E,EAAE,UAAU,EAAE,WAAW,EAAE,CAC5B,CAAC;QACF,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7E,CAAC;IAED,KAAK,CAAC,MAAM,CACV,UAAkB,EAClB,UAA4B,EAC5B,WAAmB;QAEnB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACpD,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,CACnC,cAAc,IAAI,CAAC,aAAa,EAAE;;+CAEO,IAAI,CAAC,MAAM,CAAC,KAAK;;;;;;;;;8BASlC,IAAI;8BACJ,GAAG;;;;;yBAKR,EACnB,EAAE,UAAU,EAAE,WAAW,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,EAAE,CACrD,CAAC;QACF,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACzF,CAAC;CACF"}

package/dist/src/analytics/duckdb.d.ts

@@ -0,0 +1,39 @@
+import { type AnalyticsBackend } from './backend.js';
+import { type MetricDefinition, type VariantMetricStats } from './metrics.js';
+export interface DuckDbOptions {
+    /** DuckDB database file. Default `:memory:` (the data lives in the Parquet files). */
+    database?: string;
+    /**
+     * Statements run on every new connection: `INSTALL httpfs; LOAD httpfs;`, `CREATE SECRET …` for
+     * S3/GCS credentials, `SET memory_limit = '1GB'`.
+     */
+    setup?: string[];
+}
+type Sql = (statement: string) => Promise<void>;
+type Select = <T = Record<string, unknown>>(statement: string) => Promise<T[]>;
+/** A lazily-created DuckDB instance. `@duckdb/node-api` is imported on first use only. */
+export declare class DuckDb {
+    #private;
+    private readonly options;
+    constructor(options?: DuckDbOptions);
+    withConnection<T>(fn: (sql: Sql, select: Select) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/**
+ * Level 2 of DESIGN §12: reads the Parquet files the `parquet` sink writes, with DuckDB, in process.
+ * No server to run. Point it at the same `path`. Queries scan files, so run it where a few seconds
+ * of CPU are fine (the worker computes and caches results; the console reads the cache).
+ */
+export declare class DuckDbBackend implements AnalyticsBackend {
+    #private;
+    private readonly options;
+    readonly kind = "duckdb";
+    constructor(options: DuckDbOptions & {
+        path: string;
+    });
+    exposures(experiment: string, environment: string): Promise<Record<string, number>>;
+    metric(experiment: string, definition: MetricDefinition, environment: string): Promise<Record<string, VariantMetricStats>>;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=duckdb.d.ts.map

package/dist/src/analytics/duckdb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckdb.d.ts","sourceRoot":"","sources":["../../../src/analytics/duckdb.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,gBAAgB,EAAgB,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,KAAK,gBAAgB,EAGrB,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,aAAa;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,KAAK,GAAG,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAChD,KAAK,MAAM,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;AAkB/E,0FAA0F;AAC1F,qBAAa,MAAM;;IAGL,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,GAAE,aAAkB,EAAI;IAiBtD,cAAc,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAchF;IAEK,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAG3B;CACF;AAMD;;;;GAIG;AACH,qBAAa,aAAc,YAAW,gBAAgB;;IAIxC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,QAAQ,CAAC,IAAI,YAAY;IAGzB,YAA6B,OAAO,EAAE,aAAa,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAErE;IAeK,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAOxF;IAEK,MAAM,CACV,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,gBAAgB,EAC5B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CA+B7C;IAED,KAAK,kBAEJ;CACF"}

package/dist/src/analytics/duckdb.js

@@ -0,0 +1,117 @@
+import { statsFromRow } from './backend.js';
+import { subjectAggregates, UNBOUNDED_MS, } from './metrics.js';
+/** A lazily-created DuckDB instance. `@duckdb/node-api` is imported on first use only. */
+export class DuckDb {
+    options;
+    #instance;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async #get() {
+        if (!this.#instance) {
+            let mod;
+            try {
+                mod = (await import('@duckdb/node-api'));
+            }
+            catch {
+                throw new Error('@adonis-agora/flags: the parquet sink and the duckdb analytics backend need "@duckdb/node-api". Install it.');
+            }
+            this.#instance = await mod.DuckDBInstance.create(this.options.database ?? ':memory:');
+        }
+        return this.#instance;
+    }
+    async withConnection(fn) {
+        const instance = await this.#get();
+        const connection = await instance.connect();
+        try {
+            for (const statement of this.options.setup ?? [])
+                await connection.run(statement);
+            const sql = async (statement) => {
+                await connection.run(statement);
+            };
+            const select = async (statement) => (await connection.runAndReadAll(statement)).getRowObjectsJS();
+            return await fn(sql, select);
+        }
+        finally {
+            connection.closeSync();
+        }
+    }
+    async close() {
+        this.#instance?.closeSync();
+        this.#instance = undefined;
+    }
+}
+function literal(value) {
+    return typeof value === 'number' ? String(value) : `'${value.replaceAll("'", "''")}'`;
+}
+/**
+ * Level 2 of DESIGN §12: reads the Parquet files the `parquet` sink writes, with DuckDB, in process.
+ * No server to run. Point it at the same `path`. Queries scan files, so run it where a few seconds
+ * of CPU are fine (the worker computes and caches results; the console reads the cache).
+ */
+export class DuckDbBackend {
+    options;
+    kind = 'duckdb';
+    #duck;
+    constructor(options) {
+        this.options = options;
+        this.#duck = new DuckDb(options);
+    }
+    get #glob() {
+        return literal(`${this.options.path.replace(/\/$/, '')}/**/*.parquet`);
+    }
+    /** First exposure per subject, deduped by event id like every other backend. */
+    #exposuresSql(experiment, environment) {
+        return `SELECT subject, arg_min(variant, ts) AS variant, min(ts) AS first_seen_ts
+              FROM read_parquet(${this.#glob}, hive_partitioning = true, union_by_name = true)
+             WHERE type = 'exposure' AND environment = ${literal(environment)}
+               AND experiment = ${literal(experiment)}
+             GROUP BY subject`;
+    }
+    async exposures(experiment, environment) {
+        return this.#duck.withConnection(async (_sql, select) => {
+            const rows = await select(`SELECT variant, COUNT(*) AS n FROM (${this.#exposuresSql(experiment, environment)}) GROUP BY variant`).catch(noFiles);
+            return Object.fromEntries(rows.map((row) => [row.variant, Number(row.n)]));
+        });
+    }
+    async metric(experiment, definition, environment) {
+        const { post, pre } = subjectAggregates(definition);
+        const window = definition.windowMs ?? UNBOUNDED_MS;
+        const preWindow = definition.cupedMs ?? 0;
+        return this.#duck.withConnection(async (_sql, select) => {
+            const rows = await select(`WITH x AS (${this.#exposuresSql(experiment, environment)}),
+              t AS (
+                SELECT DISTINCT ON (event_id) subject, value, ts
+                  FROM read_parquet(${this.#glob}, hive_partitioning = true, union_by_name = true)
+                 WHERE type = 'track' AND environment = ${literal(environment)}
+                   AND name = ${literal(definition.event)}
+              )
+         SELECT variant, COUNT(*) AS n,
+                SUM(y) AS sum_y, SUM(y * y) AS sum_y2,
+                SUM(xv) AS sum_x, SUM(xv * xv) AS sum_x2, SUM(xv * y) AS sum_xy
+           FROM (
+             SELECT x.variant AS variant, x.subject AS subject,
+                    CAST(${post} AS DOUBLE) AS y,
+                    CAST(${pre} AS DOUBLE) AS xv
+               FROM x
+               LEFT JOIN t
+                 ON t.subject = x.subject
+                AND t.ts >= x.first_seen_ts - ${preWindow}
+                AND t.ts < x.first_seen_ts + ${window}
+              GROUP BY x.variant, x.subject
+           )
+          GROUP BY variant`).catch(noFiles);
+            return Object.fromEntries(rows.map((row) => [String(row.variant), statsFromRow(row)]));
+        });
+    }
+    close() {
+        return this.#duck.close();
+    }
+}
+/** No Parquet file yet means no data, not an error. */
+function noFiles(error) {
+    if (/No files found|does not exist|IO Error/i.test(String(error?.message)))
+        return [];
+    throw error;
+}
+//# sourceMappingURL=duckdb.js.map

package/dist/src/analytics/duckdb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"duckdb.js","sourceRoot":"","sources":["../../../src/analytics/duckdb.ts"],"names":[],"mappings":"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"}

package/dist/src/analytics/lucid_backend.d.ts

@@ -0,0 +1,16 @@
+import { type SqlClient } from '../sql.js';
+import { type AnalyticsBackend } from './backend.js';
+import { type MetricDefinition, type VariantMetricStats } from './metrics.js';
+/**
+ * Reads the `lucid` sink's tables (`flags_exposures`, `flags_tracks`). Level 1 of DESIGN §12: fine
+ * up to tens of millions of events a month, especially with results computed by the worker and
+ * cached, as the provider does.
+ */
+export declare class LucidBackend implements AnalyticsBackend {
+    private readonly db;
+    readonly kind = "lucid";
+    constructor(db: SqlClient);
+    exposures(experiment: string, environment: string): Promise<Record<string, number>>;
+    metric(experiment: string, definition: MetricDefinition, environment: string): Promise<Record<string, VariantMetricStats>>;
+}
+//# sourceMappingURL=lucid_backend.d.ts.map

package/dist/src/analytics/lucid_backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lucid_backend.d.ts","sourceRoot":"","sources":["../../../src/analytics/lucid_backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAS,KAAK,SAAS,EAAY,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,KAAK,gBAAgB,EAAgB,MAAM,cAAc,CAAC;AACnE,OAAO,EACL,KAAK,gBAAgB,EAGrB,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAEtB;;;;GAIG;AACH,qBAAa,YAAa,YAAW,gBAAgB;IAGvC,OAAO,CAAC,QAAQ,CAAC,EAAE;IAF/B,QAAQ,CAAC,IAAI,WAAW;IAExB,YAA6B,EAAE,EAAE,SAAS,EAAI;IAExC,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAOxF;IAEK,MAAM,CACV,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,gBAAgB,EAC5B,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,CA4B7C;CACF"}

package/dist/src/analytics/lucid_backend.js

@@ -0,0 +1,45 @@
+import { query, toNumber } from '../sql.js';
+import { statsFromRow } from './backend.js';
+import { subjectAggregates, UNBOUNDED_MS, } from './metrics.js';
+/**
+ * Reads the `lucid` sink's tables (`flags_exposures`, `flags_tracks`). Level 1 of DESIGN §12: fine
+ * up to tens of millions of events a month, especially with results computed by the worker and
+ * cached, as the provider does.
+ */
+export class LucidBackend {
+    db;
+    kind = 'lucid';
+    constructor(db) {
+        this.db = db;
+    }
+    async exposures(experiment, environment) {
+        const rows = await query(this.db, 'SELECT variant, COUNT(*) AS n FROM flags_exposures WHERE environment = ? AND experiment = ? GROUP BY variant', [environment, experiment]);
+        return Object.fromEntries(rows.map((row) => [row.variant, toNumber(row.n)]));
+    }
+    async metric(experiment, definition, environment) {
+        const { post, pre } = subjectAggregates(definition);
+        const window = definition.windowMs ?? UNBOUNDED_MS;
+        const preWindow = definition.cupedMs ?? 0;
+        const rows = await query(this.db, `SELECT variant,
+              COUNT(*) AS n,
+              SUM(y) AS sum_y, SUM(y * y) AS sum_y2,
+              SUM(xv) AS sum_x, SUM(xv * xv) AS sum_x2, SUM(xv * y) AS sum_xy
+         FROM (
+           SELECT x.variant AS variant, x.subject AS subject,
+                  ${post} AS y,
+                  ${pre} AS xv
+             FROM flags_exposures x
+             LEFT JOIN flags_tracks t
+               ON t.subject = x.subject
+              AND t.environment = x.environment
+              AND t.name = ?
+              AND t.ts >= x.first_seen_ts - ?
+              AND t.ts < x.first_seen_ts + ?
+            WHERE x.environment = ? AND x.experiment = ?
+            GROUP BY x.variant, x.subject
+         ) per_subject
+        GROUP BY variant`, [definition.event, preWindow, window, environment, experiment]);
+        return Object.fromEntries(rows.map((row) => [String(row.variant), statsFromRow(row)]));
+    }
+}
+//# sourceMappingURL=lucid_backend.js.map

package/dist/src/analytics/lucid_backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lucid_backend.js","sourceRoot":"","sources":["../../../src/analytics/lucid_backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAkB,QAAQ,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAyB,YAAY,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAEL,iBAAiB,EACjB,YAAY,GAEb,MAAM,cAAc,CAAC;AAEtB;;;;GAIG;AACH,MAAM,OAAO,YAAY;IAGM,EAAE;IAFtB,IAAI,GAAG,OAAO,CAAC;IAExB,YAA6B,EAAa;kBAAb,EAAE;IAAc,CAAC;IAE9C,KAAK,CAAC,SAAS,CAAC,UAAkB,EAAE,WAAmB;QACrD,MAAM,IAAI,GAAG,MAAM,KAAK,CACtB,IAAI,CAAC,EAAE,EACP,8GAA8G,EAC9G,CAAC,WAAW,EAAE,UAAU,CAAC,CAC1B,CAAC;QACF,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,CAAC;IAED,KAAK,CAAC,MAAM,CACV,UAAkB,EAClB,UAA4B,EAC5B,WAAmB;QAEnB,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,GAAG,iBAAiB,CAAC,UAAU,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,IAAI,YAAY,CAAC;QACnD,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC;QAC1C,MAAM,IAAI,GAAG,MAAM,KAAK,CACtB,IAAI,CAAC,EAAE,EACP;;;;;;oBAMc,IAAI;oBACJ,GAAG;;;;;;;;;;;yBAWE,EACnB,CAAC,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,CAAC,CAC/D,CAAC;QACF,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACzF,CAAC;CACF"}

package/dist/src/analytics/metrics.d.ts

@@ -0,0 +1,50 @@
+/** How a metric aggregates a subject's tracked events. */
+export type MetricKind = 'conversion' | 'count' | 'sum';
+export interface MetricOptions {
+    description?: string;
+    /** Count only events within this many ms after the subject's first exposure. Default: no limit. */
+    windowMs?: number;
+    /**
+     * CUPED: use the same metric over this many ms BEFORE exposure as a covariate. Shrinks variance
+     * (decisions with fewer subjects) when behaviour is stable over time. Default: off.
+     */
+    cupedMs?: number;
+    /** Which direction is good. Default `increase`. Shown in the console; guardrails alert on the bad one. */
+    direction?: 'increase' | 'decrease';
+}
+export interface MetricDefinition extends MetricOptions {
+    kind: MetricKind;
+    /** Tracked event name (`flags.track(subject, 'purchase')`). */
+    event: string;
+}
+/** Builders for `metrics` in `config/flags.ts`. */
+export declare const metric: {
+    /** Share of subjects who did `event` at least once after exposure. */
+    conversion(event: string, options?: MetricOptions): MetricDefinition;
+    /** Times each subject did `event` after exposure, averaged per subject. */
+    count(event: string, options?: MetricOptions): MetricDefinition;
+    /** Sum of the events' `value` per subject (revenue per user), averaged per subject. */
+    sum(event: string, options?: MetricOptions): MetricDefinition;
+};
+/** Per-variant sufficient statistics of one metric (y) and its CUPED covariate (x). */
+export interface VariantMetricStats {
+    n: number;
+    sumY: number;
+    sumY2: number;
+    sumX: number;
+    sumX2: number;
+    sumXY: number;
+}
+/**
+ * The per-subject aggregation, as SQL expressions over a joined track row `t` and exposure row `x`.
+ * Shared by every SQL backend so they agree on what a metric means. The time windows live in the
+ * expressions, not in a WHERE clause: a subject with no event in the window must still count, as a
+ * zero, in the denominator.
+ */
+export declare function subjectAggregates(definition: MetricDefinition): {
+    post: string;
+    pre: string;
+};
+/** A window far beyond any real experiment, so "no limit" needs no special SQL. */
+export declare const UNBOUNDED_MS: number;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/src/analytics/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/analytics/metrics.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,OAAO,GAAG,KAAK,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,mGAAmG;IACnG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0GAA0G;IAC1G,SAAS,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;CACrC;AAED,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACrD,IAAI,EAAE,UAAU,CAAC;IACjB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;CACf;AAED,mDAAmD;AACnD,eAAO,MAAM,MAAM;IACjB,sEAAsE;IACtE,UAAU,QAAQ,MAAM,YAAW,aAAa,GAAQ,gBAAgB;IAGxE,2EAA2E;IAC3E,KAAK,QAAQ,MAAM,YAAW,aAAa,GAAQ,gBAAgB;IAGnE,uFAAuF;IACvF,GAAG,QAAQ,MAAM,YAAW,aAAa,GAAQ,gBAAgB;CAGlE,CAAC;AAEF,uFAAuF;AACvF,MAAM,WAAW,kBAAkB;IACjC,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,gBAAgB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CAc7F;AAED,mFAAmF;AACnF,eAAO,MAAM,YAAY,QAA+B,CAAC"}

package/dist/src/analytics/metrics.js

@@ -0,0 +1,42 @@
+/** Builders for `metrics` in `config/flags.ts`. */
+export const metric = {
+    /** Share of subjects who did `event` at least once after exposure. */
+    conversion(event, options = {}) {
+        return { ...options, kind: 'conversion', event };
+    },
+    /** Times each subject did `event` after exposure, averaged per subject. */
+    count(event, options = {}) {
+        return { ...options, kind: 'count', event };
+    },
+    /** Sum of the events' `value` per subject (revenue per user), averaged per subject. */
+    sum(event, options = {}) {
+        return { ...options, kind: 'sum', event };
+    },
+};
+/**
+ * The per-subject aggregation, as SQL expressions over a joined track row `t` and exposure row `x`.
+ * Shared by every SQL backend so they agree on what a metric means. The time windows live in the
+ * expressions, not in a WHERE clause: a subject with no event in the window must still count, as a
+ * zero, in the denominator.
+ */
+export function subjectAggregates(definition) {
+    const window = Math.trunc(Number(definition.windowMs ?? UNBOUNDED_MS));
+    const preWindow = Math.trunc(Number(definition.cupedMs ?? 0));
+    if (!Number.isFinite(window) || window <= 0)
+        throw new RangeError('metric windowMs must be > 0');
+    if (!Number.isFinite(preWindow) || preWindow < 0)
+        throw new RangeError('metric cupedMs must be ≥ 0');
+    const post = `t.ts >= x.first_seen_ts AND t.ts < x.first_seen_ts + ${window}`;
+    const pre = `t.ts < x.first_seen_ts AND t.ts >= x.first_seen_ts - ${preWindow}`;
+    const agg = (condition) => {
+        if (definition.kind === 'conversion')
+            return `MAX(CASE WHEN ${condition} THEN 1 ELSE 0 END)`;
+        if (definition.kind === 'count')
+            return `SUM(CASE WHEN ${condition} THEN 1 ELSE 0 END)`;
+        return `COALESCE(SUM(CASE WHEN ${condition} THEN t.value ELSE 0 END), 0)`;
+    };
+    return { post: agg(post), pre: preWindow > 0 ? agg(pre) : '0' };
+}
+/** A window far beyond any real experiment, so "no limit" needs no special SQL. */
+export const UNBOUNDED_MS = 100 * 365 * 24 * 3600 * 1000;
+//# sourceMappingURL=metrics.js.map

package/dist/src/analytics/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/analytics/metrics.ts"],"names":[],"mappings":"AAsBA,mDAAmD;AACnD,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,sEAAsE;IACtE,UAAU,CAAC,KAAa,EAAE,OAAO,GAAkB,EAAE;QACnD,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC;IACnD,CAAC;IACD,2EAA2E;IAC3E,KAAK,CAAC,KAAa,EAAE,OAAO,GAAkB,EAAE;QAC9C,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9C,CAAC;IACD,uFAAuF;IACvF,GAAG,CAAC,KAAa,EAAE,OAAO,GAAkB,EAAE;QAC5C,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;IAC5C,CAAC;CACF,CAAC;AAYF;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA4B;IAC5D,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,IAAI,YAAY,CAAC,CAAC,CAAC;IACvE,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,6BAA6B,CAAC,CAAC;IACjG,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC;QAC9C,MAAM,IAAI,UAAU,CAAC,4BAA4B,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,wDAAwD,MAAM,EAAE,CAAC;IAC9E,MAAM,GAAG,GAAG,wDAAwD,SAAS,EAAE,CAAC;IAChF,MAAM,GAAG,GAAG,CAAC,SAAiB,EAAE,EAAE;QAChC,IAAI,UAAU,CAAC,IAAI,KAAK,YAAY;YAAE,OAAO,iBAAiB,SAAS,qBAAqB,CAAC;QAC7F,IAAI,UAAU,CAAC,IAAI,KAAK,OAAO;YAAE,OAAO,iBAAiB,SAAS,qBAAqB,CAAC;QACxF,OAAO,0BAA0B,SAAS,+BAA+B,CAAC;IAC5E,CAAC,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAClE,CAAC;AAED,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC"}

package/dist/src/analytics/results.d.ts

@@ -0,0 +1,80 @@
+import { type FlagDefinition, type SrmResult } from '@adonis-agora/flags-core';
+import type { AnalyticsBackend } from './backend.js';
+import type { MetricDefinition } from './metrics.js';
+/** The variant name exposures of global-holdout subjects are recorded under. */
+export declare const HOLDOUT_VARIANT = "__holdout__";
+/** An experiment as the results service sees it. */
+export interface ExperimentSpec {
+    /** Experiment key (the flag key unless `experiment.key` says otherwise). */
+    key: string;
+    flag: string;
+    /** Environment whose exposures and events are analysed. Default `production`. */
+    environment?: string;
+    /** Metric name → definition. */
+    metrics: Record<string, MetricDefinition>;
+    /** Metrics that must not get worse; a significant move the wrong way is flagged. */
+    guardrails?: string[];
+    /** Control variant. Default: the flag's `offVariant`. */
+    control?: string;
+    /** Confidence level for fixed-horizon intervals. Default 0.95. */
+    confidence?: number;
+}
+export interface Comparison {
+    variant: string;
+    test: 'proportion' | 'welch' | 'cuped';
+    difference: number;
+    relativeLift: number;
+    pValue: number;
+    interval: [number, number];
+    significant: boolean;
+    /** Always-valid (sequential) version of the same comparison: safe to peek. */
+    sequential: {
+        pValue: number;
+        interval: [number, number];
+        significant: boolean;
+    };
+    /** CUPED only. */
+    varianceReduction?: number;
+    /** `better` / `worse` according to the metric's direction, when significant. */
+    verdict: 'better' | 'worse' | 'inconclusive';
+}
+export interface MetricResult {
+    name: string;
+    kind: MetricDefinition['kind'];
+    event: string;
+    direction: 'increase' | 'decrease';
+    guardrail: boolean;
+    variants: Array<{
+        variant: string;
+        n: number;
+        mean: number;
+    }>;
+    comparisons: Comparison[];
+    /** A guardrail that got significantly worse in some variant. */
+    alert: boolean;
+}
+export interface ExperimentResults {
+    experiment: string;
+    flag: string;
+    environment: string;
+    control: string;
+    computedAt: string;
+    exposures: Record<string, number>;
+    /** Subjects of the global holdout who reached this experiment (not compared). */
+    holdout: number;
+    /** `null` when the flag has no single split to compare against. */
+    srm: (SrmResult & {
+        expected: Record<string, number>;
+    }) | null;
+    metrics: MetricResult[];
+    /** Comparisons computed with too few subjects (< 2 per variant) are skipped and listed here. */
+    warnings: string[];
+}
+/**
+ * The configured split weights, when the flag assigns through exactly one split (fallthrough or a
+ * single rule). SRM is only meaningful against one known allocation.
+ */
+export declare function expectedWeights(flag: FlagDefinition): Record<string, number> | null;
+/** Computes everything the console shows for an experiment. */
+export declare function computeResults(backend: AnalyticsBackend, spec: ExperimentSpec, flag: FlagDefinition | undefined, previous?: ExperimentResults): Promise<ExperimentResults>;
+//# sourceMappingURL=results.d.ts.map

package/dist/src/analytics/results.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.ts","sourceRoot":"","sources":["../../../src/analytics/results.ts"],"names":[],"mappings":"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"}

package/dist/src/analytics/results.js

@@ -0,0 +1,143 @@
+import { cupedTest, proportionTest, sequentialTest, srmTest, welchTest, } from '@adonis-agora/flags-core';
+/** The variant name exposures of global-holdout subjects are recorded under. */
+export const HOLDOUT_VARIANT = '__holdout__';
+/**
+ * The configured split weights, when the flag assigns through exactly one split (fallthrough or a
+ * single rule). SRM is only meaningful against one known allocation.
+ */
+export function expectedWeights(flag) {
+    const splits = [flag.fallthrough, ...(flag.rules ?? []).map((rule) => rule.serve)].filter((serve) => 'split' in serve);
+    if (splits.length !== 1)
+        return null;
+    const weights = {};
+    for (const arm of splits[0].split)
+        if (arm.weight > 0)
+            weights[arm.variant] = (weights[arm.variant] ?? 0) + arm.weight;
+    return weights;
+}
+function asCuped(stats) {
+    return stats;
+}
+/** Computes everything the console shows for an experiment. */
+export async function computeResults(backend, spec, flag, previous) {
+    const control = spec.control ?? flag?.offVariant ?? 'control';
+    const confidence = spec.confidence ?? 0.95;
+    const warnings = [];
+    const environment = spec.environment ?? 'production';
+    const allExposures = await backend.exposures(spec.key, environment);
+    // Global-holdout subjects are recorded under a reserved variant; they are not an arm of this
+    // experiment, so they are reported apart and left out of every comparison.
+    const holdout = allExposures[HOLDOUT_VARIANT] ?? 0;
+    const exposures = Object.fromEntries(Object.entries(allExposures).filter(([variant]) => variant !== HOLDOUT_VARIANT));
+    let srm = null;
+    const expected = flag ? expectedWeights(flag) : null;
+    if (expected && Object.keys(expected).length >= 2) {
+        const variants = Object.keys(expected);
+        const observed = variants.map((variant) => exposures[variant] ?? 0);
+        if (observed.reduce((a, b) => a + b, 0) > 0) {
+            srm = {
+                ...srmTest(observed, variants.map((v) => expected[v])),
+                expected,
+            };
+        }
+    }
+    const metrics = [];
+    for (const [name, definition] of Object.entries(spec.metrics)) {
+        const { [HOLDOUT_VARIANT]: _held, ...stats } = await backend.metric(spec.key, definition, environment);
+        const direction = definition.direction ?? 'increase';
+        const guardrail = spec.guardrails?.includes(name) ?? false;
+        const variantNames = [...new Set([...Object.keys(exposures), ...Object.keys(stats)])].sort((a, b) => (a === control ? -1 : b === control ? 1 : a.localeCompare(b)));
+        const result = {
+            name,
+            kind: definition.kind,
+            event: definition.event,
+            direction,
+            guardrail,
+            variants: variantNames.map((variant) => {
+                const s = stats[variant];
+                return { variant, n: s?.n ?? 0, mean: s && s.n > 0 ? s.sumY / s.n : 0 };
+            }),
+            comparisons: [],
+            alert: false,
+        };
+        const base = stats[control];
+        for (const variant of variantNames) {
+            if (variant === control)
+                continue;
+            const treatment = stats[variant];
+            if (!base || !treatment || base.n < 2 || treatment.n < 2) {
+                warnings.push(`${name}: not enough subjects to compare "${variant}" with "${control}" yet`);
+                continue;
+            }
+            const prior = previous?.metrics
+                .find((m) => m.name === name)
+                ?.comparisons.find((c) => c.variant === variant)?.sequential.pValue;
+            const plainControl = { n: base.n, sum: base.sumY, sumSquares: base.sumY2 };
+            const plainTreatment = { n: treatment.n, sum: treatment.sumY, sumSquares: treatment.sumY2 };
+            let comparison;
+            if (definition.cupedMs && definition.cupedMs > 0) {
+                const r = cupedTest(asCuped(base), asCuped(treatment), confidence);
+                comparison = {
+                    test: 'cuped',
+                    difference: r.difference,
+                    relativeLift: r.relativeLift,
+                    pValue: r.pValue,
+                    interval: r.interval,
+                    significant: r.pValue < 1 - confidence,
+                    varianceReduction: r.varianceReduction,
+                };
+            }
+            else if (definition.kind === 'conversion') {
+                const r = proportionTest({ n: base.n, conversions: base.sumY }, { n: treatment.n, conversions: treatment.sumY }, confidence);
+                comparison = {
+                    test: 'proportion',
+                    difference: r.difference,
+                    relativeLift: r.relativeLift,
+                    pValue: r.pValue,
+                    interval: r.interval,
+                    significant: r.pValue < 1 - confidence,
+                };
+            }
+            else {
+                const r = welchTest(plainControl, plainTreatment, confidence);
+                comparison = {
+                    test: 'welch',
+                    difference: r.difference,
+                    relativeLift: r.relativeLift,
+                    pValue: r.pValue,
+                    interval: r.interval,
+                    significant: r.pValue < 1 - confidence,
+                };
+            }
+            const seq = sequentialTest(plainControl, plainTreatment, {
+                alpha: 1 - confidence,
+                ...(prior !== undefined ? { previousPValue: prior } : {}),
+            });
+            const improves = direction === 'increase' ? comparison.difference > 0 : comparison.difference < 0;
+            const verdict = comparison.significant ? (improves ? 'better' : 'worse') : 'inconclusive';
+            result.comparisons.push({
+                variant,
+                ...comparison,
+                sequential: { pValue: seq.pValue, interval: seq.interval, significant: seq.significant },
+                verdict,
+            });
+            // Guardrails alert on the always-valid test, so watching them daily does not cry wolf.
+            if (guardrail && seq.significant && !improves)
+                result.alert = true;
+        }
+        metrics.push(result);
+    }
+    return {
+        experiment: spec.key,
+        flag: spec.flag,
+        environment,
+        control,
+        computedAt: new Date().toISOString(),
+        exposures,
+        holdout,
+        srm,
+        metrics,
+        warnings,
+    };
+}
+//# sourceMappingURL=results.js.map