@adonis-agora/flags 0.0.0-stage → 0.1.0

package/dist/src/manager.js

@@ -0,0 +1,333 @@
+import { evaluate, } from '@adonis-agora/flags-core';
+import { HOLDOUT_VARIANT } from './analytics/results.js';
+import { effectiveDeclarations } from './declare.js';
+import { runEnrichers } from './enrichers.js';
+import { EVENT_SCHEMA_VERSION, exposureId, uuidv7 } from './events/event.js';
+import { toContext, toSubject } from './subject.js';
+/**
+ * The entry point: `flags.for(user).enabled('new_player')`. Evaluation is in memory against the
+ * ruleset the source keeps fresh; nothing here waits on the database except an opt-in sticky lookup
+ * (once per scope).
+ */
+export class FlagsManager {
+    deps;
+    #fakes;
+    #warnedTransactional = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get environment() {
+        return this.deps.environment;
+    }
+    get app() {
+        return this.deps.app;
+    }
+    get admin() {
+        if (!this.deps.admin) {
+            throw new Error('flags admin is not available here (a tenant edits flags on its control-plane)');
+        }
+        return this.deps.admin;
+    }
+    /** Flags declared in code. */
+    get declarations() {
+        return this.deps.declarations;
+    }
+    /** Every known flag: declared in code or created in the console (code wins). */
+    effectiveDeclarations() {
+        return effectiveDeclarations(this.deps.declarations, this.ruleset());
+    }
+    /** The ruleset this process evaluates against. */
+    ruleset() {
+        return this.deps.source.current();
+    }
+    status() {
+        return {
+            app: this.deps.app,
+            environment: this.deps.environment,
+            source: this.deps.source.status(),
+            buffer: this.deps.buffer
+                ? {
+                    pending: this.deps.buffer.pending,
+                    published: this.deps.buffer.published,
+                    dropped: this.deps.buffer.dropped,
+                }
+                : null,
+            transport: this.deps.transport
+                ? { name: this.deps.transport.name, ...this.deps.transport.capabilities }
+                : null,
+        };
+    }
+    /** Reloads the ruleset now (after an edit in this process, or from a command). */
+    refresh() {
+        return this.deps.source.refresh();
+    }
+    /** A scope for one subject. In HTTP handlers prefer `ctx.flags`, which the middleware builds. */
+    for(subject, attributes = {}) {
+        return new FlagsScope(this, toSubject(subject), attributes);
+    }
+    /** A scope whose subject is resolved on the first flag read. */
+    forLazy(resolve, attributes = {}) {
+        return new FlagsScope(this, resolve, attributes);
+    }
+    /** The declared default: from code, else from the console declaration in the ruleset. */
+    declaredDefault(key) {
+        return this.deps.declarations[key]?.default ?? this.ruleset().flags[key]?.declaration?.default;
+    }
+    /** @internal Evaluation with fakes, usage counting and enrichers. */
+    evaluateFor(key, fallback, context, options) {
+        this.deps.usage?.hit(key);
+        const fake = this.#fakes;
+        let details;
+        if (fake?.has(key)) {
+            details = {
+                flagKey: key,
+                value: fake.get(key),
+                variant: String(fake.get(key)),
+                reason: 'STATIC',
+                flagMetadata: { faked: true },
+            };
+        }
+        else {
+            details = evaluate(this.ruleset(), key, fallback, context, options);
+            if (details.errorCode === 'FLAG_NOT_FOUND' && key in this.deps.declarations) {
+                // Declared in code, not configured yet: serving the declared default is the normal state,
+                // not an error (alerts on reason ERROR would fire for every new flag).
+                details = {
+                    flagKey: key,
+                    value: details.value,
+                    reason: 'DEFAULT',
+                    flagMetadata: { ...details.flagMetadata, configured: false },
+                };
+            }
+        }
+        if (details.errorCode && details.errorCode !== 'FLAG_NOT_FOUND') {
+            this.deps.logger?.warn(`[flags] ${key}: ${details.errorCode} ${details.errorMessage ?? ''}`.trim());
+        }
+        const enrichers = this.deps.enrichers ?? [];
+        runEnrichers(enrichers, (e) => e.onEvaluation?.(details, context));
+        return details;
+    }
+    /** @internal Records an exposure for an experiment assignment. */
+    expose(subject, details) {
+        const experiment = details.flagMetadata.experiment;
+        if (typeof experiment !== 'string' || details.variant === undefined)
+            return;
+        const holdout = details.flagMetadata.holdout === true;
+        if (details.reason !== 'SPLIT' && !holdout)
+            return;
+        const subjectId = String(subject.id);
+        const event = {
+            id: exposureId(this.deps.app, this.deps.environment, experiment, subjectId),
+            schemaVersion: EVENT_SCHEMA_VERSION,
+            app: this.deps.app,
+            environment: this.deps.environment,
+            type: 'exposure',
+            flag: details.flagKey,
+            experiment,
+            variant: holdout ? HOLDOUT_VARIANT : details.variant,
+            subject: subjectId,
+            subjectType: subject.type ?? 'user',
+            ...(holdout ? { props: { holdout: true } } : {}),
+            ts: Date.now(),
+        };
+        if (this.deps.buffer?.push(event)) {
+            runEnrichers(this.deps.enrichers ?? [], (e) => e.onEvent?.(event));
+        }
+    }
+    /** Records a tracked event (a conversion) for a subject. */
+    async track(subject, name, options = {}) {
+        const normalized = toSubject(subject);
+        if (!normalized)
+            throw new Error('flags.track() needs a subject');
+        if (this.#fakes)
+            return;
+        const event = {
+            id: uuidv7(),
+            schemaVersion: EVENT_SCHEMA_VERSION,
+            app: this.deps.app,
+            environment: this.deps.environment,
+            type: 'track',
+            name,
+            subject: String(normalized.id),
+            subjectType: normalized.type ?? 'user',
+            ...(options.value !== undefined ? { value: options.value } : {}),
+            ...(options.props !== undefined ? { props: options.props } : {}),
+            ts: Date.now(),
+        };
+        runEnrichers(this.deps.enrichers ?? [], (e) => e.onEvent?.(event));
+        const transport = this.deps.transport;
+        if (options.client && transport) {
+            if (transport.capabilities.transactional) {
+                await transport.publish([event], { client: options.client });
+                return;
+            }
+            if (!this.#warnedTransactional) {
+                this.#warnedTransactional = true;
+                this.deps.logger?.warn(`[flags] the "${transport.name}" transport is not transactional: tracked events are sent after commit, and are lost if the process dies in between`);
+            }
+            if (options.client.after) {
+                options.client.after('commit', () => {
+                    this.deps.buffer?.push(event);
+                });
+                return;
+            }
+        }
+        this.deps.buffer?.push(event);
+    }
+    /** Experiment results as last computed by the worker (or `null`), for this process's environment by default. */
+    results(experiment, environment) {
+        return this.deps.results ? this.deps.results(experiment, environment) : Promise.resolve(null);
+    }
+    /** Deletes everything stored about a subject in every sink that supports it. */
+    async forget(subject) {
+        const normalized = toSubject(subject);
+        if (!normalized)
+            return;
+        await this.deps.forget?.(String(normalized.id));
+    }
+    /** @internal */
+    async attributesFor(subject) {
+        if (!subject || !this.deps.attributes)
+            return {};
+        return this.deps.attributes(subject);
+    }
+    /** @internal */
+    stickyFor(subject) {
+        if (!subject || !this.deps.sticky)
+            return undefined;
+        return this.deps.sticky(String(subject.id));
+    }
+    /**
+     * Replaces flag values for the duration of a test. Every evaluation of a faked key returns the
+     * given value; tracked events are dropped. Returns a function that restores real evaluation.
+     *
+     * ```ts
+     * const restore = flags.fake({ checkout_v2: 'b' })
+     * // …
+     * restore()
+     * ```
+     */
+    fake(values) {
+        this.#fakes = new Map(Object.entries(values));
+        return () => this.restore();
+    }
+    restore() {
+        this.#fakes = undefined;
+    }
+}
+/**
+ * Flags for one subject. Results are memoized for the life of the scope (one request), so a flag
+ * cannot change value halfway through rendering a page. The subject may be given directly or as a
+ * resolver that runs on the first read (what `ctx.flags` uses).
+ */
+export class FlagsScope {
+    manager;
+    attributes;
+    #memo = new Map();
+    #subject;
+    #context;
+    #sticky;
+    #resolver;
+    #resolved;
+    constructor(manager, subject, attributes = {}) {
+        this.manager = manager;
+        this.attributes = attributes;
+        if (typeof subject === 'function') {
+            const resolve = subject;
+            this.#resolver = async () => toSubject(await resolve());
+            this.#subject = Promise.resolve(undefined);
+        }
+        else {
+            this.#subject = Promise.resolve(subject);
+        }
+    }
+    /** The subject this scope evaluates for (resolved on first use). */
+    subject() {
+        if (!this.#resolver)
+            return this.#subject;
+        this.#resolved ??= this.#resolver();
+        return this.#resolved;
+    }
+    #ctx() {
+        this.#context ??= this.subject().then(async (subject) => {
+            const resolved = await this.manager.attributesFor(subject);
+            return toContext(subject, { ...resolved, ...this.attributes });
+        });
+        return this.#context;
+    }
+    async #options(key) {
+        const flag = this.manager.ruleset().flags[key];
+        if (!flag?.experiment)
+            return {};
+        this.#sticky ??= this.subject().then((subject) => this.manager.stickyFor(subject)?.catch(() => ({})) ?? {});
+        return { sticky: await this.#sticky };
+    }
+    async #evaluate(key) {
+        const cached = this.#memo.get(key);
+        if (cached)
+            return cached;
+        const fallback = (this.manager.declaredDefault(key) ?? null);
+        const details = this.manager.evaluateFor(key, fallback, await this.#ctx(), await this.#options(key));
+        this.#memo.set(key, details);
+        return details;
+    }
+    /** Full evaluation details (value, variant, reason, error). Records an exposure for experiments. */
+    async details(key) {
+        const details = await this.#evaluate(key);
+        const subject = await this.subject();
+        if (subject)
+            this.manager.expose(subject, details);
+        return details;
+    }
+    /** The flag's value. */
+    async value(key) {
+        return (await this.details(key)).value;
+    }
+    /** Whether a boolean flag is on. */
+    async enabled(key) {
+        return (await this.details(key)).value === true;
+    }
+    async disabled(key) {
+        return !(await this.enabled(key));
+    }
+    /**
+     * `true` when a boolean flag is on, or — given variants — when the flag serves one of them.
+     * What the Edge `@flag` tag compiles to.
+     */
+    async matches(key, ...variants) {
+        const details = await this.details(key);
+        if (variants.length === 0)
+            return details.value === true;
+        return variants.includes(details.variant ?? String(details.value));
+    }
+    /** The variant name served (experiments). Falls back to the value as a string. */
+    async variant(key) {
+        const details = await this.details(key);
+        return details.variant ?? String(details.value);
+    }
+    /**
+     * Values of several flags at once — for the frontend. Without `keys`, only flags declared with
+     * `client: true` are included, so internal flag names never reach the browser by accident.
+     * Experiment exposures are NOT recorded here unless `expose: true`: values sent to a page are not
+     * necessarily seen.
+     */
+    async all(keys, options = {}) {
+        const declarations = this.manager.effectiveDeclarations();
+        const list = keys ?? Object.keys(declarations).filter((key) => declarations[key]?.client);
+        const out = {};
+        for (const key of list) {
+            out[key] = options.expose
+                ? (await this.details(key)).value
+                : (await this.#evaluate(key)).value;
+        }
+        return out;
+    }
+    /** Records a tracked event for this scope's subject. */
+    async track(name, options = {}) {
+        const subject = await this.subject();
+        if (!subject)
+            throw new Error('cannot track for an anonymous subject');
+        return this.manager.track(subject, name, options);
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/src/manager.js.map

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

package/dist/src/openfeature/provider.d.ts

@@ -0,0 +1,36 @@
+import type { EvaluationContext, JsonValue as OFJsonValue, Provider, ResolutionDetails, TrackingEventDetails } from '@openfeature/server-sdk';
+import type { FlagsManager } from '../manager.js';
+/**
+ * An OpenFeature provider backed by the same engine as `flags.for()`: same ruleset, same buckets,
+ * same exposures. Use it when your code talks to `@openfeature/server-sdk` (to stay vendor-neutral
+ * or to share code with services in other stacks).
+ *
+ * ```ts
+ * import { OpenFeature } from '@openfeature/server-sdk'
+ * import { AgoraFlagsProvider } from '@adonis-agora/flags/openfeature'
+ *
+ * await OpenFeature.setProviderAndWait(new AgoraFlagsProvider())
+ * const client = OpenFeature.getClient()
+ * await client.getBooleanValue('new_player', false, { targetingKey: user.id })
+ * ```
+ *
+ * The context's `targetingKey` is the subject id; `subjectType` sets the subject type; every other
+ * attribute is a targeting attribute. Tracking is OpenFeature's experimental `track()`.
+ */
+export declare class AgoraFlagsProvider implements Provider {
+    #private;
+    private readonly manager?;
+    readonly metadata: {
+        readonly name: '@adonis-agora/flags';
+    };
+    readonly runsOn: 'server';
+    readonly hooks: never[];
+    /** Pass a manager explicitly, or let it resolve the booted one. */
+    constructor(manager?: FlagsManager | undefined);
+    resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context: EvaluationContext): Promise<ResolutionDetails<boolean>>;
+    resolveStringEvaluation(flagKey: string, defaultValue: string, context: EvaluationContext): Promise<ResolutionDetails<string>>;
+    resolveNumberEvaluation(flagKey: string, defaultValue: number, context: EvaluationContext): Promise<ResolutionDetails<number>>;
+    resolveObjectEvaluation<T extends OFJsonValue>(flagKey: string, defaultValue: T, context: EvaluationContext): Promise<ResolutionDetails<T>>;
+    track(trackingEventName: string, context: EvaluationContext, details?: TrackingEventDetails): void;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/src/openfeature/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../../src/openfeature/provider.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,IAAI,WAAW,EACxB,QAAQ,EACR,iBAAiB,EACjB,oBAAoB,EACrB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAIlD;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAmB,YAAW,QAAQ;;IAMrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;IALrC,QAAQ,CAAC,QAAQ;iBAAK,IAAI,EAAE,qBAAqB;MAAY;IAC7D,QAAQ,CAAC,MAAM,EAAG,QAAQ,CAAU;IACpC,QAAQ,CAAC,KAAK,UAAM;IAEpB,mEAAmE;IACnE,YAA6B,OAAO,CAAC,EAAE,YAAY,YAAA,EAAI;IA2CjD,wBAAwB,CAC5B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,OAAO,EACrB,OAAO,EAAE,iBAAiB,uCAG3B;IAEK,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,sCAE9F;IAEK,uBAAuB,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,sCAE9F;IAEK,uBAAuB,CAAC,CAAC,SAAS,WAAW,EACjD,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,CAAC,EACf,OAAO,EAAE,iBAAiB,iCAO3B;IAED,KAAK,CACH,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,iBAAiB,EAC1B,OAAO,CAAC,EAAE,oBAAoB,GAC7B,IAAI,CAQN;CACF"}

package/dist/src/openfeature/provider.js

@@ -0,0 +1,82 @@
+import { getRuntime } from '../services/accessor.js';
+/**
+ * An OpenFeature provider backed by the same engine as `flags.for()`: same ruleset, same buckets,
+ * same exposures. Use it when your code talks to `@openfeature/server-sdk` (to stay vendor-neutral
+ * or to share code with services in other stacks).
+ *
+ * ```ts
+ * import { OpenFeature } from '@openfeature/server-sdk'
+ * import { AgoraFlagsProvider } from '@adonis-agora/flags/openfeature'
+ *
+ * await OpenFeature.setProviderAndWait(new AgoraFlagsProvider())
+ * const client = OpenFeature.getClient()
+ * await client.getBooleanValue('new_player', false, { targetingKey: user.id })
+ * ```
+ *
+ * The context's `targetingKey` is the subject id; `subjectType` sets the subject type; every other
+ * attribute is a targeting attribute. Tracking is OpenFeature's experimental `track()`.
+ */
+export class AgoraFlagsProvider {
+    manager;
+    metadata = { name: '@adonis-agora/flags' };
+    runsOn = 'server';
+    hooks = [];
+    /** Pass a manager explicitly, or let it resolve the booted one. */
+    constructor(manager) {
+        this.manager = manager;
+    }
+    get #manager() {
+        return this.manager ?? getRuntime().manager;
+    }
+    #subject(context) {
+        const key = context.targetingKey;
+        if (key === undefined || key === '')
+            return undefined;
+        return {
+            id: key,
+            ...(typeof context.subjectType === 'string' ? { type: context.subjectType } : {}),
+        };
+    }
+    #resolve(flagKey, defaultValue, context) {
+        const manager = this.#manager;
+        const { targetingKey: _key, ...attributes } = context;
+        const details = manager.evaluateFor(flagKey, defaultValue, {
+            ...attributes,
+            ...(context.targetingKey ? { targetingKey: context.targetingKey } : {}),
+        }, {});
+        const subject = this.#subject(context);
+        if (subject)
+            manager.expose(subject, details);
+        return {
+            value: details.value,
+            reason: details.reason,
+            ...(details.variant !== undefined ? { variant: details.variant } : {}),
+            ...(details.errorCode ? { errorCode: details.errorCode } : {}),
+            ...(details.errorMessage ? { errorMessage: details.errorMessage } : {}),
+            flagMetadata: details.flagMetadata,
+        };
+    }
+    async resolveBooleanEvaluation(flagKey, defaultValue, context) {
+        return this.#resolve(flagKey, defaultValue, context);
+    }
+    async resolveStringEvaluation(flagKey, defaultValue, context) {
+        return this.#resolve(flagKey, defaultValue, context);
+    }
+    async resolveNumberEvaluation(flagKey, defaultValue, context) {
+        return this.#resolve(flagKey, defaultValue, context);
+    }
+    async resolveObjectEvaluation(flagKey, defaultValue, context) {
+        return this.#resolve(flagKey, defaultValue, context);
+    }
+    track(trackingEventName, context, details) {
+        const subject = this.#subject(context);
+        if (!subject)
+            return;
+        const { value, ...props } = details ?? {};
+        void this.#manager.track(subject, trackingEventName, {
+            ...(typeof value === 'number' ? { value } : {}),
+            ...(Object.keys(props).length > 0 ? { props: props } : {}),
+        });
+    }
+}
+//# sourceMappingURL=provider.js.map

package/dist/src/openfeature/provider.js.map

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

package/dist/src/relay/relay.d.ts

@@ -0,0 +1,36 @@
+import type { Sink } from '../sinks/sink.js';
+import type { Transport } from '../transports/transport.js';
+export interface RelayOptions {
+    /** Events per batch. Default 1000 (a sink can ask for its own). */
+    batchSize?: number;
+    /** How long a lease lasts (ms) before another process may take over. Default 60000. */
+    leaseMs?: number;
+}
+export interface DrainResult {
+    sink: string;
+    delivered: number;
+    batches: number;
+    /** Another process holds the lease. */
+    busy: boolean;
+    error?: string;
+}
+/** A process-unique owner id for leases. */
+export declare function relayOwner(): string;
+/**
+ * Moves events from the transport to one sink: lease, read a batch, write it, ack (which moves the
+ * cursor). Errors leave the cursor where it was, so the batch is retried next time. The lease makes
+ * it safe for every replica to run the relay: one of them delivers per sink at a time.
+ */
+export declare class Relay {
+    private readonly transport;
+    private readonly sinks;
+    private readonly options;
+    readonly owner: string;
+    constructor(transport: Transport, sinks: Map<string, Sink>, options?: RelayOptions, owner?: string);
+    get sinkNames(): string[];
+    sink(name: string): Sink | undefined;
+    /** Delivers up to `maxBatches` batches to `name`. */
+    drain(name: string, maxBatches?: number): Promise<DrainResult>;
+    drainAll(maxBatches?: number): Promise<DrainResult[]>;
+}
+//# sourceMappingURL=relay.d.ts.map

package/dist/src/relay/relay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay.d.ts","sourceRoot":"","sources":["../../../src/relay/relay.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D,MAAM,WAAW,YAAY;IAC3B,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,4CAA4C;AAC5C,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED;;;;GAIG;AACH,qBAAa,KAAK;IAId,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAL1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YACmB,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,EACxB,OAAO,GAAE,YAAiB,EAC3C,KAAK,CAAC,EAAE,MAAM,EAQf;IAED,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;IAED,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAEnC;IAED,qDAAqD;IAC/C,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,SAAK,GAAG,OAAO,CAAC,WAAW,CAAC,CA8B/D;IAEK,QAAQ,CAAC,UAAU,SAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAItD;CACF"}

package/dist/src/relay/relay.js

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+/** A process-unique owner id for leases. */
+export function relayOwner() {
+    return `${hostname()}:${process.pid}:${randomUUID().slice(0, 8)}`;
+}
+/**
+ * Moves events from the transport to one sink: lease, read a batch, write it, ack (which moves the
+ * cursor). Errors leave the cursor where it was, so the batch is retried next time. The lease makes
+ * it safe for every replica to run the relay: one of them delivers per sink at a time.
+ */
+export class Relay {
+    transport;
+    sinks;
+    options;
+    owner;
+    constructor(transport, sinks, options = {}, owner) {
+        this.transport = transport;
+        this.sinks = sinks;
+        this.options = options;
+        this.owner = owner ?? relayOwner();
+        if (!transport.consume) {
+            throw new Error(`the "${transport.name}" transport has no consumer side; there is nothing to relay here`);
+        }
+    }
+    get sinkNames() {
+        return [...this.sinks.keys()];
+    }
+    sink(name) {
+        return this.sinks.get(name);
+    }
+    /** Delivers up to `maxBatches` batches to `name`. */
+    async drain(name, maxBatches = 20) {
+        const sink = this.sinks.get(name);
+        if (!sink)
+            throw new Error(`unknown sink "${name}"`);
+        const result = { sink: name, delivered: 0, batches: 0, busy: false };
+        for (let i = 0; i < maxBatches; i++) {
+            const delivery = await this.transport.consume(name, {
+                batchSize: sink.batchSize ?? this.options.batchSize ?? 1000,
+                leaseMs: this.options.leaseMs ?? 60_000,
+                owner: this.owner,
+            });
+            if (!delivery) {
+                result.busy = result.batches === 0;
+                break;
+            }
+            if (delivery.events.length === 0) {
+                await delivery.release();
+                break;
+            }
+            try {
+                await sink.write(delivery.events);
+                await delivery.ack();
+                result.delivered += delivery.events.length;
+                result.batches++;
+            }
+            catch (error) {
+                await delivery.fail(error);
+                result.error = error instanceof Error ? error.message : String(error);
+                break;
+            }
+        }
+        return result;
+    }
+    async drainAll(maxBatches = 20) {
+        const out = [];
+        for (const name of this.sinks.keys())
+            out.push(await this.drain(name, maxBatches));
+        return out;
+    }
+}
+//# sourceMappingURL=relay.js.map

package/dist/src/relay/relay.js.map

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

package/dist/src/relay/results_cache.d.ts

@@ -0,0 +1,20 @@
+import type { ExperimentResults } from '../analytics/results.js';
+import { type SqlDatabase } from '../sql.js';
+/** Last computed experiment results: the console reads these instead of scanning events. */
+export interface ResultsCache {
+    get(environment: string, experiment: string): Promise<ExperimentResults | null>;
+    set(environment: string, experiment: string, results: ExperimentResults): Promise<void>;
+}
+export declare class MemoryResultsCache implements ResultsCache {
+    #private;
+    get(environment: string, experiment: string): Promise<ExperimentResults | null>;
+    set(environment: string, experiment: string, results: ExperimentResults): Promise<void>;
+}
+/** `flags_results`, shared by every replica. */
+export declare class LucidResultsCache implements ResultsCache {
+    private readonly db;
+    constructor(db: SqlDatabase);
+    get(environment: string, experiment: string): Promise<ExperimentResults | null>;
+    set(environment: string, experiment: string, results: ExperimentResults): Promise<void>;
+}
+//# sourceMappingURL=results_cache.d.ts.map

package/dist/src/relay/results_cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"results_cache.d.ts","sourceRoot":"","sources":["../../../src/relay/results_cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAA+B,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAE1E,4FAA4F;AAC5F,MAAM,WAAW,YAAY;IAC3B,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAChF,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzF;AAED,qBAAa,kBAAmB,YAAW,YAAY;;IAE/C,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,qCAEhD;IACK,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,iBAE5E;CACF;AAED,gDAAgD;AAChD,qBAAa,iBAAkB,YAAW,YAAY;IACxC,OAAO,CAAC,QAAQ,CAAC,EAAE;IAA/B,YAA6B,EAAE,EAAE,WAAW,EAAI;IAE1C,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAOpF;IAEK,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW5F;CACF"}