@c9up/eon 0.1.0 → 0.2.1

package/dist/testing/FakeEonConsumer.js

@@ -0,0 +1,66 @@
+import { EonConsumerError } from "../tmq/EonConsumer.js";
+export class FakeEonConsumer {
+    #topics = [];
+    #queue = [];
+    #polled = 0;
+    #committed = 0;
+    #closed = false;
+    /** Queue messages a later `poll()` will return, in order. */
+    push(...messages) {
+        this.#queue.push(...messages);
+        return this;
+    }
+    /** How many messages have been acknowledged. */
+    get committedCount() {
+        return this.#committed;
+    }
+    /** Whether `close()` has run. */
+    get isClosed() {
+        return this.#closed;
+    }
+    #ensureOpen() {
+        if (this.#closed)
+            throw new EonConsumerError("eon: consumer is closed");
+    }
+    async subscribe(topics) {
+        this.#ensureOpen();
+        if (topics.length === 0) {
+            throw new EonConsumerError("eon: subscribe() needs at least one topic");
+        }
+        this.#topics = [...topics];
+    }
+    async subscription() {
+        this.#ensureOpen();
+        return [...this.#topics];
+    }
+    async poll(_timeoutMs) {
+        this.#ensureOpen();
+        // Drain, don't replay: a real poll never hands back the same rows twice.
+        const batch = this.#queue.splice(0, this.#queue.length);
+        this.#polled += batch.length;
+        return batch;
+    }
+    async commit() {
+        this.#ensureOpen();
+        this.#committed = this.#polled;
+        return this.#topics.map((topic) => ({ topic, vgroupId: 0 }));
+    }
+    async assignment(topics) {
+        this.#ensureOpen();
+        return (topics ?? this.#topics).map((topic) => ({ topic, vgroupId: 0 }));
+    }
+    async seek(partition) {
+        this.#ensureOpen();
+        if (partition.offset === undefined) {
+            throw new EonConsumerError("eon: seek() needs an offset");
+        }
+    }
+    async unsubscribe() {
+        this.#ensureOpen();
+        this.#topics = [];
+    }
+    async close() {
+        this.#closed = true;
+    }
+}
+//# sourceMappingURL=FakeEonConsumer.js.map

package/dist/testing/FakeEonConsumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FakeEonConsumer.js","sourceRoot":"","sources":["../../src/testing/FakeEonConsumer.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,MAAM,OAAO,eAAe;IAC3B,OAAO,GAAa,EAAE,CAAC;IACvB,MAAM,GAAiB,EAAE,CAAC;IAC1B,OAAO,GAAG,CAAC,CAAC;IACZ,UAAU,GAAG,CAAC,CAAC;IACf,OAAO,GAAG,KAAK,CAAC;IAEhB,6DAA6D;IAC7D,IAAI,CAAC,GAAG,QAAsB;QAC7B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,CAAC;QAC9B,OAAO,IAAI,CAAC;IACb,CAAC;IAED,gDAAgD;IAChD,IAAI,cAAc;QACjB,OAAO,IAAI,CAAC,UAAU,CAAC;IACxB,CAAC;IAED,iCAAiC;IACjC,IAAI,QAAQ;QACX,OAAO,IAAI,CAAC,OAAO,CAAC;IACrB,CAAC;IAED,WAAW;QACV,IAAI,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,gBAAgB,CAAC,yBAAyB,CAAC,CAAC;IACzE,CAAC;IAED,KAAK,CAAC,SAAS,CAAC,MAAgB;QAC/B,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,gBAAgB,CAAC,2CAA2C,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,YAAY;QACjB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,IAAI,CACT,UAAkB;QAElB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,yEAAyE;QACzE,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,CAAC;QAC7B,OAAO,KAAwB,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,MAAM;QACX,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC;QAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,MAAiB;QACjC,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,SAA4B;QACtC,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,SAAS,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YACpC,MAAM,IAAI,gBAAgB,CAAC,6BAA6B,CAAC,CAAC;QAC3D,CAAC;IACF,CAAC;IAED,KAAK,CAAC,WAAW;QAChB,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,KAAK;QACV,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACrB,CAAC;CACD"}

package/dist/testing/cleanup.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Test-database lifecycle for eon integration suites.
+ *
+ * Every integration file used to spell its own
+ * `await conn.exec("DROP DATABASE IF EXISTS " + TEST_DB)` in `afterAll` —
+ * seven copies of one rule, which is how a cleanup quietly stops matching its
+ * setup. Atlas ships `truncateAll` / `useTransaction` for the same reason;
+ * TDengine has no transactions, so the unit here is the database.
+ */
+import type { EonConnection } from "../connection/EonConnection.js";
+/**
+ * Drop a subscription topic if it exists. Safe to call when it never existed.
+ *
+ * Order matters: TDengine REFUSES to drop a database that still carries a
+ * topic ("Topic must be dropped first"), so a suite that creates one must drop
+ * it before {@link dropTestDatabase} or {@link createTestDatabase} — including
+ * on the setup path, where a topic left by a crashed previous run is exactly
+ * what breaks the next one.
+ */
+export declare function dropTestTopic(conn: EonConnection, topic: string, options?: {
+    retries?: number;
+    delayMs?: number;
+}): Promise<void>;
+/**
+ * Drop a test database if it exists. Safe to call when it never existed.
+ *
+ * Fails if the database still carries a topic — see {@link dropTestTopic}.
+ */
+export declare function dropTestDatabase(conn: EonConnection, database: string): Promise<void>;
+/**
+ * Drop, recreate and `USE` a test database — the setup half of a suite.
+ *
+ * Dropping FIRST is the point: a suite that crashed mid-run leaves rows behind,
+ * and a `CREATE DATABASE IF NOT EXISTS` would then run against them. A test
+ * that passes only because the previous run left the right data is worse than
+ * one that fails.
+ */
+export declare function createTestDatabase(conn: EonConnection, database: string, options?: {
+    keepMs?: number;
+}): Promise<void>;
+/**
+ * Run a body against a freshly created test database, dropping it afterwards
+ * whether the body threw or not.
+ *
+ * The `finally` is what the hand-written `afterAll` blocks kept getting right
+ * by accident: a failing assertion must still leave the server clean, or the
+ * next run inherits the wreckage of this one.
+ */
+export declare function withTestDatabase<T>(conn: EonConnection, database: string, body: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=cleanup.d.ts.map

package/dist/testing/cleanup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.d.ts","sourceRoot":"","sources":["../../src/testing/cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAqBpE;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CAClC,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GAClD,OAAO,CAAC,IAAI,CAAC,CAsBf;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CACrC,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/B,OAAO,CAAC,IAAI,CAAC,CAMf;AAED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACvC,IAAI,EAAE,aAAa,EACnB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACpB,OAAO,CAAC,CAAC,CAAC,CAOZ"}

package/dist/testing/cleanup.js

@@ -0,0 +1,88 @@
+/** TDengine identifiers: a letter or underscore, then letters, digits, underscores. */
+const IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Guard an identifier before it is interpolated into DDL.
+ *
+ * `exec` takes literal SQL — TDengine binds no `?` in DDL — so a database name
+ * reaching these helpers is concatenated. A test name is not attacker-supplied,
+ * but a typo'd one silently becomes a different statement, and `DROP DATABASE`
+ * is the statement you least want to be surprising.
+ */
+function assertIdentifier(name, what) {
+    if (!IDENTIFIER.test(name)) {
+        throw new Error(`[E_EON_TEST_IDENTIFIER] invalid ${what} '${name}'; must match ${IDENTIFIER}`);
+    }
+}
+/**
+ * Drop a subscription topic if it exists. Safe to call when it never existed.
+ *
+ * Order matters: TDengine REFUSES to drop a database that still carries a
+ * topic ("Topic must be dropped first"), so a suite that creates one must drop
+ * it before {@link dropTestDatabase} or {@link createTestDatabase} — including
+ * on the setup path, where a topic left by a crashed previous run is exactly
+ * what breaks the next one.
+ */
+export async function dropTestTopic(conn, topic, options = {}) {
+    assertIdentifier(topic, "topic name");
+    const retries = options.retries ?? 10;
+    const delayMs = options.delayMs ?? 300;
+    // TDengine rebalances a topic's partitions for a moment after a consumer
+    // disconnects, and refuses DROP TOPIC with "Topic being rebalanced" until it
+    // settles. Any suite that subscribed hits this, so the wait belongs here
+    // rather than copy-pasted into each one — and it must be BOUNDED: retrying
+    // forever would turn a real failure into a hang.
+    for (let attempt = 0;; attempt++) {
+        try {
+            await conn.exec(`DROP TOPIC IF EXISTS ${topic}`);
+            return;
+        }
+        catch (error) {
+            const rebalancing = /being rebalanced/i.test(error instanceof Error ? error.message : String(error));
+            if (!rebalancing || attempt >= retries)
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
+    }
+}
+/**
+ * Drop a test database if it exists. Safe to call when it never existed.
+ *
+ * Fails if the database still carries a topic — see {@link dropTestTopic}.
+ */
+export async function dropTestDatabase(conn, database) {
+    assertIdentifier(database, "database name");
+    await conn.exec(`DROP DATABASE IF EXISTS ${database}`);
+}
+/**
+ * Drop, recreate and `USE` a test database — the setup half of a suite.
+ *
+ * Dropping FIRST is the point: a suite that crashed mid-run leaves rows behind,
+ * and a `CREATE DATABASE IF NOT EXISTS` would then run against them. A test
+ * that passes only because the previous run left the right data is worse than
+ * one that fails.
+ */
+export async function createTestDatabase(conn, database, options = {}) {
+    assertIdentifier(database, "database name");
+    await conn.exec(`DROP DATABASE IF EXISTS ${database}`);
+    const keep = options.keepMs === undefined ? "" : ` KEEP ${options.keepMs}`;
+    await conn.exec(`CREATE DATABASE ${database}${keep}`);
+    await conn.exec(`USE ${database}`);
+}
+/**
+ * Run a body against a freshly created test database, dropping it afterwards
+ * whether the body threw or not.
+ *
+ * The `finally` is what the hand-written `afterAll` blocks kept getting right
+ * by accident: a failing assertion must still leave the server clean, or the
+ * next run inherits the wreckage of this one.
+ */
+export async function withTestDatabase(conn, database, body) {
+    await createTestDatabase(conn, database);
+    try {
+        return await body();
+    }
+    finally {
+        await dropTestDatabase(conn, database);
+    }
+}
+//# sourceMappingURL=cleanup.js.map

package/dist/testing/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../src/testing/cleanup.ts"],"names":[],"mappings":"AAWA,uFAAuF;AACvF,MAAM,UAAU,GAAG,0BAA0B,CAAC;AAE9C;;;;;;;GAOG;AACH,SAAS,gBAAgB,CAAC,IAAY,EAAE,IAAY;IACnD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACd,mCAAmC,IAAI,KAAK,IAAI,iBAAiB,UAAU,EAAE,CAC7E,CAAC;IACH,CAAC;AACF,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,IAAmB,EACnB,KAAa,EACb,UAAkD,EAAE;IAEpD,gBAAgB,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC;IACtC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,GAAG,CAAC;IAEvC,yEAAyE;IACzE,6EAA6E;IAC7E,yEAAyE;IACzE,2EAA2E;IAC3E,iDAAiD;IACjD,KAAK,IAAI,OAAO,GAAG,CAAC,GAAI,OAAO,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC;YACJ,MAAM,IAAI,CAAC,IAAI,CAAC,wBAAwB,KAAK,EAAE,CAAC,CAAC;YACjD,OAAO;QACR,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,WAAW,GAAG,mBAAmB,CAAC,IAAI,CAC3C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACtD,CAAC;YACF,IAAI,CAAC,WAAW,IAAI,OAAO,IAAI,OAAO;gBAAE,MAAM,KAAK,CAAC;YACpD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QAC9D,CAAC;IACF,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,IAAmB,EACnB,QAAgB;IAEhB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAC5C,MAAM,IAAI,CAAC,IAAI,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACvC,IAAmB,EACnB,QAAgB,EAChB,UAA+B,EAAE;IAEjC,gBAAgB,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;IAC5C,MAAM,IAAI,CAAC,IAAI,CAAC,2BAA2B,QAAQ,EAAE,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,EAAE,CAAC;IAC3E,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,QAAQ,GAAG,IAAI,EAAE,CAAC,CAAC;IACtD,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,QAAQ,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,IAAmB,EACnB,QAAgB,EAChB,IAAsB;IAEtB,MAAM,kBAAkB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACzC,IAAI,CAAC;QACJ,OAAO,MAAM,IAAI,EAAE,CAAC;IACrB,CAAC;YAAS,CAAC;QACV,MAAM,gBAAgB,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACxC,CAAC;AACF,CAAC"}

package/dist/testing/index.d.ts

@@ -6,19 +6,19 @@
  * integration suites skip via `describeIfTdengine` (mirrors atlas's "no external
  * DB required for unit tests" posture). CI sets it, so the roundtrip runs for
  * real — no silent cap. The fake store + factory need NO server.
+ *
+ * This module is RUNNER-AGNOSTIC and must stay that way: it is a shipped export
+ * path, so anything it imports becomes a hard requirement for every consumer.
+ * `describeIfTdengine` lives in `./vitest.js` for that reason.
  */
 import type { EonConnectionConfig } from "../connection/config.js";
 import type { EonConnection } from "../connection/EonConnection.js";
+export { createTestDatabase, dropTestDatabase, dropTestTopic, withTestDatabase, } from "./cleanup.js";
 export { type FactoryBuilder, factory } from "./Factory.js";
 export { FakeEonConnection } from "./FakeEonConnection.js";
+export { FakeEonConsumer } from "./FakeEonConsumer.js";
 /** Whether an `EON_TEST_URL` is configured (a live TDengine is reachable). */
 export declare function hasTestServer(): boolean;
-/**
- * Register a suite that runs only when a test server is configured, else skips —
- * so integration suites gate uniformly. CI (with `EON_TEST_URL`) runs them for
- * real; local dev without a server skips them.
- */
-export declare function describeIfTdengine(name: string, factory: () => void): void;
 /**
  * Open a connection to the test server (`EON_TEST_URL`), applying root/taosdata
  * defaults and a generous connect-retry for a cold docker server. Callers gate

package/dist/testing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAGpE,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAQ3D,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAM1E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,SAAS,GAAE,OAAO,CAAC,mBAAmB,CAAM,GAC1C,OAAO,CAAC,aAAa,CAAC,CAexB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAClC,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,MAAM,GACR,OAAO,CAAC,IAAI,CAAC,CAMf"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAGpE,OAAO,EACN,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,KAAK,cAAc,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAQvD,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,SAAS,GAAE,OAAO,CAAC,mBAAmB,CAAM,GAC1C,OAAO,CAAC,aAAa,CAAC,CAexB;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAClC,IAAI,EAAE,aAAa,EACnB,EAAE,EAAE,MAAM,GACR,OAAO,CAAC,IAAI,CAAC,CAMf"}

package/dist/testing/index.js

@@ -6,11 +6,16 @@
  * integration suites skip via `describeIfTdengine` (mirrors atlas's "no external
  * DB required for unit tests" posture). CI sets it, so the roundtrip runs for
  * real — no silent cap. The fake store + factory need NO server.
+ *
+ * This module is RUNNER-AGNOSTIC and must stay that way: it is a shipped export
+ * path, so anything it imports becomes a hard requirement for every consumer.
+ * `describeIfTdengine` lives in `./vitest.js` for that reason.
  */
-import { describe } from "vitest";
 import { connectWsEon } from "../connection/websocket.js";
+export { createTestDatabase, dropTestDatabase, dropTestTopic, withTestDatabase, } from "./cleanup.js";
 export { factory } from "./Factory.js";
 export { FakeEonConnection } from "./FakeEonConnection.js";
+export { FakeEonConsumer } from "./FakeEonConsumer.js";
 /** The live TDengine URL for integration tests (taosAdapter WS), or `undefined`. */
 function testUrl() {
     const url = process.env.EON_TEST_URL;
@@ -20,19 +25,6 @@ function testUrl() {
 export function hasTestServer() {
     return testUrl() !== undefined;
 }
-/**
- * Register a suite that runs only when a test server is configured, else skips —
- * so integration suites gate uniformly. CI (with `EON_TEST_URL`) runs them for
- * real; local dev without a server skips them.
- */
-export function describeIfTdengine(name, factory) {
-    if (hasTestServer()) {
-        describe(name, factory);
-    }
-    else {
-        describe.skip(name, factory);
-    }
-}
 /**
  * Open a connection to the test server (`EON_TEST_URL`), applying root/taosdata
  * defaults and a generous connect-retry for a cold docker server. Callers gate

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAGlC,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EAAuB,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,oFAAoF;AACpF,SAAS,OAAO;IACf,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACrC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACpE,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa;IAC5B,OAAO,OAAO,EAAE,KAAK,SAAS,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,OAAmB;IACnE,IAAI,aAAa,EAAE,EAAE,CAAC;QACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;SAAM,CAAC;QACP,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC7B,YAA0C,EAAE;IAE5C,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACd,4GAA4G,CAC5G,CAAC;IACH,CAAC;IACD,OAAO,YAAY,CAAC;QACnB,GAAG;QACH,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,UAAU;QACpB,cAAc,EAAE,EAAE;QAClB,gBAAgB,EAAE,GAAG;QACrB,GAAG,SAAS;KACZ,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,IAAmB,EACnB,EAAU;IAEV,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,8CAA8C,EAAE,GAAG,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,IAAI,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC;IACjD,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC;AACzD,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D,OAAO,EACN,kBAAkB,EAClB,gBAAgB,EAChB,aAAa,EACb,gBAAgB,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAuB,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,oFAAoF;AACpF,SAAS,OAAO;IACf,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACrC,OAAO,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AACpE,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa;IAC5B,OAAO,OAAO,EAAE,KAAK,SAAS,CAAC;AAChC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC7B,YAA0C,EAAE;IAE5C,MAAM,GAAG,GAAG,OAAO,EAAE,CAAC;IACtB,IAAI,CAAC,GAAG,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CACd,4GAA4G,CAC5G,CAAC;IACH,CAAC;IACD,OAAO,YAAY,CAAC;QACnB,GAAG;QACH,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,UAAU;QACpB,cAAc,EAAE,EAAE;QAClB,gBAAgB,EAAE,GAAG;QACrB,GAAG,SAAS;KACZ,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAClC,IAAmB,EACnB,EAAU;IAEV,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,8CAA8C,EAAE,GAAG,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,IAAI,CAAC,IAAI,CAAC,2BAA2B,EAAE,EAAE,CAAC,CAAC;IACjD,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC;AACzD,CAAC"}

package/dist/testing/vitest.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Register a suite that runs only when a test server is configured, else skips —
+ * so integration suites gate uniformly. CI (with `EON_TEST_URL`) runs them for
+ * real; local dev without a server skips them.
+ */
+export declare function describeIfTdengine(name: string, factory: () => void): void;
+//# sourceMappingURL=vitest.d.ts.map

package/dist/testing/vitest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.d.ts","sourceRoot":"","sources":["../../src/testing/vitest.ts"],"names":[],"mappings":"AAeA;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAM1E"}

package/dist/testing/vitest.js

@@ -0,0 +1,28 @@
+/**
+ * The vitest-flavoured half of eon's test helpers.
+ *
+ * Split out on purpose. `@c9up/eon/testing` is a SHIPPED export path, and a
+ * static `import { describe } from "vitest"` made merely importing it require
+ * vitest — which eon carries as a devDependency only. An app on helix (ream's
+ * own runner) reaching for `factory` or `FakeEonConnection` would have died on
+ * `Cannot find package 'vitest'`, the same shape as the @c9up/comet bug.
+ *
+ * Everything runner-agnostic stays in `./index.ts`. Only this file needs the
+ * runner, and vitest is declared an OPTIONAL peer for it.
+ */
+import { describe } from "vitest";
+import { hasTestServer } from "./index.js";
+/**
+ * Register a suite that runs only when a test server is configured, else skips —
+ * so integration suites gate uniformly. CI (with `EON_TEST_URL`) runs them for
+ * real; local dev without a server skips them.
+ */
+export function describeIfTdengine(name, factory) {
+    if (hasTestServer()) {
+        describe(name, factory);
+    }
+    else {
+        describe.skip(name, factory);
+    }
+}
+//# sourceMappingURL=vitest.js.map

package/dist/testing/vitest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.js","sourceRoot":"","sources":["../../src/testing/vitest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,OAAmB;IACnE,IAAI,aAAa,EAAE,EAAE,CAAC;QACrB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACzB,CAAC;SAAM,CAAC;QACP,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;AACF,CAAC"}

package/dist/tmq/EonConsumer.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Data subscription — TDengine's TMQ, as a transport-neutral seam.
+ *
+ * eon could write and read; it could not be TOLD when something arrived. TMQ is
+ * how TDengine streams changes to a consumer group, and without it an app that
+ * wants a live dashboard has to poll a `SELECT` on a timer.
+ *
+ * Mirrors {@link EonConnection}'s posture: this file declares the contract and
+ * leaks no ws type, so a native transport can implement the same seam later
+ * without any consumer changing.
+ */
+/** Where a consumer group starts when it has no committed offset. */
+export type EonOffsetReset = "earliest" | "latest" | "none";
+export interface EonConsumerConfig {
+    /** taosAdapter WebSocket endpoint, e.g. `ws://localhost:6041`. */
+    url: string;
+    /**
+     * The consumer group.
+     *
+     * Two consumers sharing a group split the partitions between them; two with
+     * DIFFERENT groups each receive everything. Getting this wrong is the
+     * classic way to either duplicate every message or silently process half.
+     */
+    groupId: string;
+    /** Identifies this consumer within its group, in server-side diagnostics. */
+    clientId?: string;
+    user?: string;
+    password?: string;
+    token?: string;
+    database?: string;
+    /** Where to start with no committed offset. Default: `latest`. */
+    offsetReset?: EonOffsetReset;
+    /**
+     * Commit offsets on a timer.
+     *
+     * Default FALSE, which deviates from the driver: auto-commit acknowledges
+     * messages the app may not have finished with, so a crash loses them with no
+     * trace. Opt in once your handler is idempotent.
+     */
+    autoCommit?: boolean;
+    /** Auto-commit period in ms. Ignored unless `autoCommit` is true. */
+    autoCommitIntervalMs?: number;
+    /** Include the source table name with each message. Default: true. */
+    withTableName?: boolean;
+}
+/** One topic's worth of a poll. */
+export interface EonMessage<T = Record<string, unknown>> {
+    topic: string;
+    rows: T[];
+}
+/** A position in one topic's virtual group. */
+export interface EonTopicPartition {
+    topic: string;
+    vgroupId: number;
+    offset?: bigint;
+    begin?: bigint;
+    end?: bigint;
+}
+/**
+ * A subscribed consumer.
+ *
+ * The lifecycle is `subscribe` → `poll` in a loop → `commit` → `close`.
+ */
+export interface EonConsumer {
+    /** Start receiving from these topics. Replaces any previous subscription. */
+    subscribe(topics: string[]): Promise<void>;
+    /** The topics currently subscribed to, as the server sees them. */
+    subscription(): Promise<string[]>;
+    /**
+     * Wait up to `timeoutMs` for messages. Resolves to an empty array on timeout
+     * — that is a normal quiet period, not an error.
+     */
+    poll<T = Record<string, unknown>>(timeoutMs: number): Promise<EonMessage<T>[]>;
+    /** Acknowledge everything polled so far. */
+    commit(): Promise<EonTopicPartition[]>;
+    /** The partitions assigned to this consumer. */
+    assignment(topics?: string[]): Promise<EonTopicPartition[]>;
+    /** Move one partition to an offset. */
+    seek(partition: EonTopicPartition): Promise<void>;
+    /** Stop receiving, without closing the connection. */
+    unsubscribe(): Promise<void>;
+    /** Release the consumer. Safe to call twice. */
+    close(): Promise<void>;
+}
+/**
+ * Raised by every consumer operation.
+ *
+ * Follows {@link EonConnectionError}'s shape — the connector's numeric code is
+ * carried verbatim rather than swallowed, so a caller can branch on it.
+ */
+export declare class EonConsumerError extends Error {
+    /** The underlying TDengine numeric error code, when the failure came from the connector. */
+    readonly code?: number;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        code?: number;
+    });
+}
+//# sourceMappingURL=EonConsumer.d.ts.map

package/dist/tmq/EonConsumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EonConsumer.d.ts","sourceRoot":"","sources":["../../src/tmq/EonConsumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,qEAAqE;AACrE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IACjC,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,WAAW,CAAC,EAAE,cAAc,CAAC;IAC7B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,qEAAqE;IACrE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,sEAAsE;IACtE,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,mCAAmC;AACnC,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,CAAC,EAAE,CAAC;CACV;AAED,+CAA+C;AAC/C,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC3B,6EAA6E;IAC7E,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,mEAAmE;IACnE,YAAY,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC;;;OAGG;IACH,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAC5B,4CAA4C;IAC5C,MAAM,IAAI,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IACvC,gDAAgD;IAChD,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAC5D,uCAAuC;IACvC,IAAI,CAAC,SAAS,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,sDAAsD;IACtD,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,gDAAgD;IAChD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAC1C,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAEX,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;CAQzE"}

package/dist/tmq/EonConsumer.js

@@ -0,0 +1,27 @@
+/**
+ * Data subscription — TDengine's TMQ, as a transport-neutral seam.
+ *
+ * eon could write and read; it could not be TOLD when something arrived. TMQ is
+ * how TDengine streams changes to a consumer group, and without it an app that
+ * wants a live dashboard has to poll a `SELECT` on a timer.
+ *
+ * Mirrors {@link EonConnection}'s posture: this file declares the contract and
+ * leaks no ws type, so a native transport can implement the same seam later
+ * without any consumer changing.
+ */
+/**
+ * Raised by every consumer operation.
+ *
+ * Follows {@link EonConnectionError}'s shape — the connector's numeric code is
+ * carried verbatim rather than swallowed, so a caller can branch on it.
+ */
+export class EonConsumerError extends Error {
+    /** The underlying TDengine numeric error code, when the failure came from the connector. */
+    code;
+    constructor(message, options) {
+        super(message, options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.name = "EonConsumerError";
+        this.code = options?.code;
+    }
+}
+//# sourceMappingURL=EonConsumer.js.map

package/dist/tmq/EonConsumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EonConsumer.js","sourceRoot":"","sources":["../../src/tmq/EonConsumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAkFH;;;;;GAKG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAC1C,4FAA4F;IACnF,IAAI,CAAU;IAEvB,YAAY,OAAe,EAAE,OAA4C;QACxE,KAAK,CACJ,OAAO,EACP,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CACnE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,CAAC;IAC3B,CAAC;CACD"}

package/dist/tmq/index.d.ts

@@ -0,0 +1,4 @@
+/** `@c9up/eon/tmq` — data subscription, without the rest of the barrel. */
+export { type EonConsumer, type EonConsumerConfig, EonConsumerError, type EonMessage, type EonOffsetReset, type EonTopicPartition, } from "./EonConsumer.js";
+export { connectWsConsumer } from "./websocket.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/tmq/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tmq/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,iBAAiB,GACtB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/tmq/index.js

@@ -0,0 +1,4 @@
+/** `@c9up/eon/tmq` — data subscription, without the rest of the barrel. */
+export { EonConsumerError, } from "./EonConsumer.js";
+export { connectWsConsumer } from "./websocket.js";
+//# sourceMappingURL=index.js.map

package/dist/tmq/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tmq/index.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,OAAO,EAGN,gBAAgB,GAIhB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/tmq/websocket.d.ts

@@ -0,0 +1,11 @@
+import { type EonConsumer, type EonConsumerConfig } from "./EonConsumer.js";
+/**
+ * Open a consumer against a taosAdapter WebSocket endpoint.
+ *
+ * `autoCommit` defaults to FALSE, where the driver defaults it on. Auto-commit
+ * acknowledges messages the handler may not have finished with, so a crash
+ * drops them silently; a subscription that loses data without saying so is
+ * worse than one that redelivers.
+ */
+export declare function connectWsConsumer(config: EonConsumerConfig): Promise<EonConsumer>;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/tmq/websocket.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/tmq/websocket.ts"],"names":[],"mappings":"AAeA,OAAO,EACN,KAAK,WAAW,EAChB,KAAK,iBAAiB,EAItB,MAAM,kBAAkB,CAAC;AAgD1B;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACtC,MAAM,EAAE,iBAAiB,GACvB,OAAO,CAAC,WAAW,CAAC,CAyItB"}