@c9up/eon 0.1.0

package/src/services/connection.ts

@@ -0,0 +1,89 @@
+/**
+ * Default `connection` singleton — ergonomic access to the configured eon
+ * connection from anywhere, mirroring `@c9up/atlas/services/db`.
+ *
+ *   import connection from '@c9up/eon/services/connection'
+ *
+ *   const rows = await connection.query('SELECT server_version()')
+ *
+ * Populated by `EonProvider.boot()`. The instance is whatever
+ * `timeseries.connections[default]` resolves to — a ws `EonConnection` today, a
+ * future native impl behind the same seam tomorrow.
+ */
+
+import type {
+	EonColumnarIngest,
+	EonConnection,
+	EonSchemalessOptions,
+} from "../connection/EonConnection.js";
+
+let instance: EonConnection | undefined;
+
+/** @internal Bind the singleton (called by EonProvider.boot). */
+export function setConnection(connection: EonConnection): void {
+	instance = connection;
+}
+
+/**
+ * @internal Unbind the singleton IF it still points at `connection` (called by
+ * EonProvider.shutdown). Ownership-guarded: when a second provider rebound the
+ * singleton, an older provider's shutdown must not clear the newer binding —
+ * otherwise `connection.*` after shutdown would dereference a closed handle.
+ */
+export function clearConnection(connection: EonConnection): void {
+	if (instance === connection) instance = undefined;
+}
+
+/** @internal Read the singleton (or `undefined` pre-boot). */
+export function getConnection(): EonConnection | undefined {
+	return instance;
+}
+
+/** The bound connection, or a descriptive throw if accessed before boot. */
+function requireInstance(): EonConnection {
+	if (!instance) {
+		throw new Error(
+			"[eon] connection singleton accessed before EonProvider.boot() ran. " +
+				"Check that `@c9up/eon/provider` is listed in your reamrc.ts providers " +
+				"and that `config/timeseries.ts` defines at least one connection.",
+		);
+	}
+	return instance;
+}
+
+/**
+ * Forwards each `EonConnection` member to the bound instance (throwing until
+ * boot binds it). A plain forwarding object rather than a `Proxy` keeps the
+ * generic `query<T>` typed and cast-free (AC9) — the seam surface is small and
+ * explicit.
+ */
+const connection: EonConnection = {
+	get transport() {
+		return requireInstance().transport;
+	},
+	exec(sql: string): Promise<{ rowsAffected: number }> {
+		return requireInstance().exec(sql);
+	},
+	query<T = Record<string, unknown>>(sql: string): Promise<T[]> {
+		return requireInstance().query<T>(sql);
+	},
+	ping(): Promise<void> {
+		return requireInstance().ping();
+	},
+	ingestColumnar(
+		request: EonColumnarIngest,
+	): Promise<{ rowsAffected: number }> {
+		return requireInstance().ingestColumnar(request);
+	},
+	schemaless(
+		lines: readonly string[],
+		options?: EonSchemalessOptions,
+	): Promise<void> {
+		return requireInstance().schemaless(lines, options);
+	},
+	close(): Promise<void> {
+		return requireInstance().close();
+	},
+};
+
+export default connection;

package/src/testing/Factory.ts

@@ -0,0 +1,186 @@
+/**
+ * `factory` / `FactoryBuilder` — Lucid/atlas-shaped test-data factory for
+ * time-series points (58.6), mirroring atlas `testing/Factory.ts`.
+ *
+ * Named states, ad-hoc merges, stubbing (build without persisting), and a
+ * minimal `create`/`createMany` that persists through a literal `INSERT` via
+ * `EonConnection.exec` — working against a {@link FakeEonConnection} OR a real
+ * one. Hydration resolves columns/tags via the 58.3 metadata getters, NEVER
+ * `key in instance` (the `@Column() declare x` pitfall, memory
+ * `project_atlas_declare_hydration`).
+ *
+ * Named boundary: `create()` is a TEST-ONLY insert, NOT the 58.4
+ * `SuperTableRepository` ingest API — the two coexist (the factory stays
+ * test-scoped) once a live repository is in play.
+ */
+
+import type { EonConnection } from "../connection/EonConnection.js";
+import {
+	getColumnMetadata,
+	getTagMetadata,
+	getTimestampColumn,
+} from "../decorators/superTable.js";
+import { compileStatementNative } from "../query/native.js";
+import {
+	orderTimestampFirst,
+	requireSuperTableName,
+} from "../schema/compile.js";
+import { childTableName } from "../schema/sync.js";
+
+/** A concrete, `@SuperTable`-decorated point class (has a no-arg constructor). */
+type PointConstructor<T extends object> = (new () => T) & {
+	readonly name: string;
+};
+
+/** A named state — mutates an in-progress data object in place. */
+type StateFn = (data: Record<string, unknown>) => void;
+
+export interface FactoryBuilder<T extends object> {
+	/** Override fields for the NEXT build (reset after consumption). */
+	merge(overrides: Record<string, unknown>): FactoryBuilder<T>;
+	/** Declare a named variation, stored on the factory's state map. */
+	state(name: string, fn: StateFn): FactoryBuilder<T>;
+	/** Activate declared states for the NEXT build (compose in order; reset after). */
+	apply(...names: string[]): FactoryBuilder<T>;
+	/** Build a data object without persisting or instantiating. */
+	make(): Record<string, unknown>;
+	/** Build `count` data objects without persisting. */
+	makeMany(count: number): Record<string, unknown>[];
+	/** Build an INSTANCE without persisting (Lucid `makeStubbed`). */
+	makeStubbed(): T;
+	/** Build + persist a single point through `conn.exec` (literal INSERT). */
+	create(conn: EonConnection): Promise<T>;
+	/** Build + persist `count` points. */
+	createMany(count: number, conn: EonConnection): Promise<T[]>;
+}
+
+export function factory<T extends object>(
+	EntityClass: PointConstructor<T>,
+	defaults: () => Record<string, unknown>,
+): FactoryBuilder<T> {
+	const states = new Map<string, StateFn>();
+	let pendingOverrides: Record<string, unknown> = {};
+	let pendingStates: string[] = [];
+
+	const buildData = (): Record<string, unknown> => {
+		const data: Record<string, unknown> = {
+			...defaults(),
+			...pendingOverrides,
+		};
+		for (const name of pendingStates) {
+			const fn = states.get(name);
+			if (!fn) {
+				throw new Error(
+					`[E_EON_FACTORY_STATE] state '${name}' is not defined on ${EntityClass.name}Factory`,
+				);
+			}
+			fn(data);
+		}
+		return data;
+	};
+
+	const resetPending = (): void => {
+		pendingOverrides = {};
+		pendingStates = [];
+	};
+
+	/** Hydrate an instance from data, assigning only declared columns/tags. */
+	const hydrate = (data: Record<string, unknown>): T => {
+		const instance = new EntityClass();
+		const known = new Set<string>([
+			...getColumnMetadata(EntityClass).map((c) => c.propertyKey),
+			...getTagMetadata(EntityClass).map((t) => t.propertyKey),
+		]);
+		const assignable: Record<string, unknown> = {};
+		for (const key of known) {
+			if (key in data) assignable[key] = data[key];
+		}
+		Object.assign(instance, assignable);
+		return instance;
+	};
+
+	const persist = async (
+		conn: EonConnection,
+		data: Record<string, unknown>,
+	): Promise<T> => {
+		const stable = requireSuperTableName(EntityClass);
+		const tsProperty = getTimestampColumn(EntityClass);
+		if (tsProperty === undefined) {
+			throw new Error(
+				`[E_EON_NO_TIMESTAMP] super-table '${stable}' has no @Timestamp column`,
+			);
+		}
+		const columns = getColumnMetadata(EntityClass);
+		const tsColumn = columns.find((c) => c.propertyKey === tsProperty);
+		if (tsColumn === undefined) {
+			throw new Error(
+				`[E_EON_NO_TIMESTAMP] super-table '${stable}' @Timestamp column '${tsProperty}' is not registered`,
+			);
+		}
+		const ordered = orderTimestampFirst(columns, tsColumn, tsProperty);
+		const tags = getTagMetadata(EntityClass);
+		const tagValues = tags.map((t) => data[t.propertyKey] ?? null);
+		const table = childTableName(stable, tagValues);
+		const row = ordered.map((c) => data[c.propertyKey] ?? null);
+
+		const { statements } = compileStatementNative(
+			{
+				kind: "insert",
+				table,
+				using: stable,
+				tags: tagValues,
+				columns: ordered.map((c) => c.propertyKey),
+				rows: [row],
+				literal: true,
+			},
+			"tdengine",
+		);
+		for (const sql of statements) await conn.exec(sql);
+		return hydrate(data);
+	};
+
+	const builder: FactoryBuilder<T> = {
+		merge(overrides) {
+			pendingOverrides = { ...pendingOverrides, ...overrides };
+			return builder;
+		},
+		state(name, fn) {
+			states.set(name, fn);
+			return builder;
+		},
+		apply(...names) {
+			pendingStates.push(...names);
+			return builder;
+		},
+		make() {
+			const data = buildData();
+			resetPending();
+			return data;
+		},
+		makeMany(count) {
+			const rows: Record<string, unknown>[] = [];
+			for (let i = 0; i < count; i++) rows.push(buildData());
+			resetPending();
+			return rows;
+		},
+		makeStubbed() {
+			const data = buildData();
+			resetPending();
+			return hydrate(data);
+		},
+		async create(conn) {
+			const data = buildData();
+			resetPending();
+			return persist(conn, data);
+		},
+		async createMany(count, conn) {
+			const rows: Record<string, unknown>[] = [];
+			for (let i = 0; i < count; i++) rows.push(buildData());
+			resetPending();
+			const created: T[] = [];
+			for (const data of rows) created.push(await persist(conn, data));
+			return created;
+		},
+	};
+	return builder;
+}

package/src/testing/FakeEonConnection.ts

@@ -0,0 +1,351 @@
+/**
+ * `FakeEonConnection` — a hand-rolled in-memory `EonConnection` for fast,
+ * deterministic unit tests without a live TDengine (58.6). The atlas analogue is
+ * a REAL in-memory SQLite (`testing/TestDatabase.ts`); TDengine has no embeddable
+ * engine, so this is a deliberately narrow test double, NOT a SQL engine.
+ *
+ * ── Scope (named boundary) ─────────────────────────────────────────────────
+ *  - `exec(sql)` RECORDS every statement (assertable via {@link statements}) and,
+ *    for recognised `CREATE TABLE`/`CREATE STABLE`/`INSERT` forms, updates a
+ *    per-table row store.
+ *  - `query(sql)` answers ONLY flat `SELECT [cols] FROM t [WHERE col <op> val]
+ *    [LIMIT n]`. Windowed / aggregate SQL (`INTERVAL`/`FILL`/`PARTITION BY`/
+ *    `avg(...)`) is NOT interpreted — it throws `E_EON_FAKE_UNSUPPORTED` pointing
+ *    the caller to the docker integration harness (`describeIfTdengine`).
+ *  - `ingestColumnar`/`schemaless` are STMT/line-protocol paths that need a live
+ *    connector — they throw `E_EON_FAKE_UNSUPPORTED`. (The 58.6 factory persists
+ *    through literal `exec` INSERTs, which the store DOES handle.)
+ *  - `ping()`/`close()` are no-ops.
+ */
+
+import type {
+	EonColumnarIngest,
+	EonConnection,
+	EonSchemalessOptions,
+} from "../connection/EonConnection.js";
+
+type Row = Record<string, unknown>;
+
+const WINDOWED = /\b(INTERVAL|FILL|PARTITION\s+BY|SLIDING)\b/i;
+
+export class FakeEonConnection implements EonConnection {
+	readonly transport: "fake" = "fake";
+	/** Every `exec`ed statement, in order — assert against this in tests. */
+	readonly statements: string[] = [];
+	readonly #store = new Map<string, Row[]>();
+
+	async exec(sql: string): Promise<{ rowsAffected: number }> {
+		this.statements.push(sql);
+		const trimmed = sql.trim();
+		if (/^CREATE\s+(STABLE|TABLE)\b/i.test(trimmed)) {
+			const table = extractCreateTarget(trimmed);
+			if (table !== undefined && !this.#store.has(table)) {
+				this.#store.set(table, []);
+			}
+			return { rowsAffected: 0 };
+		}
+		if (/^INSERT\s+INTO\b/i.test(trimmed)) {
+			const rows = parseInsert(trimmed);
+			if (rows !== undefined) {
+				const existing = this.#store.get(rows.table) ?? [];
+				existing.push(...rows.rows);
+				this.#store.set(rows.table, existing);
+				return { rowsAffected: rows.rows.length };
+			}
+		}
+		if (/^DELETE\s+FROM\b/i.test(trimmed)) {
+			const affected = this.#applyDelete(trimmed);
+			return { rowsAffected: affected };
+		}
+		// DROP / USE / other DDL: recorded, no store change.
+		if (/^DROP\s+(STABLE|TABLE)\b/i.test(trimmed)) {
+			const table = extractDropTarget(trimmed);
+			if (table !== undefined) this.#store.delete(table);
+		}
+		return { rowsAffected: 0 };
+	}
+
+	query<T = Row>(sql: string): Promise<T[]>;
+	async query(sql: string): Promise<Row[]> {
+		const trimmed = sql.trim();
+		if (WINDOWED.test(trimmed) || hasAggregate(trimmed)) {
+			throw new Error(
+				`[E_EON_FAKE_UNSUPPORTED] FakeEonConnection answers only flat SELECT; windowed/aggregate SQL needs a live TDengine (use describeIfTdengine). Query: ${trimmed}`,
+			);
+		}
+		const parsed = parseSelect(trimmed);
+		if (parsed === undefined) {
+			throw new Error(
+				`[E_EON_FAKE_UNSUPPORTED] FakeEonConnection could not parse this SELECT: ${trimmed}`,
+			);
+		}
+		let rows = [...(this.#store.get(parsed.table) ?? [])];
+		if (parsed.where !== undefined) {
+			const { column, op, value } = parsed.where;
+			rows = rows.filter((r) => compareOp(r[column], op, value));
+		}
+		if (parsed.limit !== undefined) rows = rows.slice(0, parsed.limit);
+		if (parsed.columns === "*") return rows;
+		const cols = parsed.columns;
+		return rows.map((r) => {
+			const projected: Row = {};
+			for (const c of cols) projected[c] = r[c];
+			return projected;
+		});
+	}
+
+	async ingestColumnar(
+		request: EonColumnarIngest,
+	): Promise<{ rowsAffected: number }> {
+		void request;
+		throw new Error(
+			"[E_EON_FAKE_UNSUPPORTED] FakeEonConnection has no STMT columnar path; test bulk ingest against a live TDengine (describeIfTdengine).",
+		);
+	}
+
+	async schemaless(
+		lines: readonly string[],
+		options?: EonSchemalessOptions,
+	): Promise<void> {
+		void lines;
+		void options;
+		throw new Error(
+			"[E_EON_FAKE_UNSUPPORTED] FakeEonConnection has no line-protocol path; test schemaless ingest against a live TDengine (describeIfTdengine).",
+		);
+	}
+
+	async ping(): Promise<void> {}
+	async close(): Promise<void> {}
+
+	/** Clear recorded statements and the row store. */
+	reset(): void {
+		this.statements.length = 0;
+		this.#store.clear();
+	}
+
+	/** Read the current rows for a table (a copy) — a test-inspection helper. */
+	rows(table: string): Row[] {
+		return [...(this.#store.get(table) ?? [])];
+	}
+
+	#applyDelete(sql: string): number {
+		const match =
+			/^DELETE\s+FROM\s+`([^`]+)`\s+WHERE\s+`([^`]+)`\s*=\s*(.+)$/i.exec(sql);
+		if (match === null) return 0;
+		const [, table, column, rawValue] = match;
+		if (table === undefined || column === undefined || rawValue === undefined) {
+			return 0;
+		}
+		const value = parseLiteral(rawValue.trim());
+		const existing = this.#store.get(table);
+		if (existing === undefined) return 0;
+		const kept = existing.filter((r) => r[column] !== value);
+		this.#store.set(table, kept);
+		return existing.length - kept.length;
+	}
+}
+
+/** Detect a function-call in the SELECT projection (`avg(...)`, `count(*)`, …). */
+function hasAggregate(sql: string): boolean {
+	const match = /^SELECT\s+(.+?)\s+FROM\b/i.exec(sql);
+	if (match === null) return false;
+	const projection = match[1] ?? "";
+	return /[A-Za-z_][A-Za-z0-9_]*\s*\(/.test(projection);
+}
+
+function extractCreateTarget(sql: string): string | undefined {
+	const match =
+		/^CREATE\s+(?:STABLE|TABLE)\s+(?:IF\s+NOT\s+EXISTS\s+)?`([^`]+)`/i.exec(
+			sql,
+		);
+	return match?.[1];
+}
+
+function extractDropTarget(sql: string): string | undefined {
+	const match = /^DROP\s+(?:STABLE|TABLE)\s+(?:IF\s+EXISTS\s+)?`([^`]+)`/i.exec(
+		sql,
+	);
+	return match?.[1];
+}
+
+interface ParsedInsert {
+	table: string;
+	rows: Row[];
+}
+
+/** Parse a literal `INSERT` (plain or `USING … TAGS`) into rows keyed by column. */
+function parseInsert(sql: string): ParsedInsert | undefined {
+	const tableMatch = /^INSERT\s+INTO\s+`([^`]+)`/i.exec(sql);
+	const table = tableMatch?.[1];
+	if (table === undefined) return undefined;
+	// Strip an optional child-create `USING `stb` TAGS (...)` clause.
+	const body = sql.replace(/\bUSING\s+`[^`]+`\s+TAGS\s*\([^)]*\)/i, "");
+	const colsMatch = /\(([^)]*)\)\s*VALUES/i.exec(body);
+	const valuesPart = body.slice(body.search(/VALUES/i) + "VALUES".length);
+	if (colsMatch === null) return undefined;
+	const columns = (colsMatch[1] ?? "")
+		.split(",")
+		.map((c) => c.trim().replace(/^`|`$/g, ""));
+	const rows: Row[] = [];
+	for (const tuple of splitTuples(valuesPart)) {
+		const values = splitValues(tuple).map(parseLiteral);
+		const row: Row = {};
+		columns.forEach((c, i) => {
+			row[c] = values[i];
+		});
+		rows.push(row);
+	}
+	return { table, rows };
+}
+
+interface ParsedSelect {
+	columns: "*" | string[];
+	table: string;
+	where?: { column: string; op: string; value: unknown };
+	limit?: number;
+}
+
+function parseSelect(sql: string): ParsedSelect | undefined {
+	const match =
+		/^SELECT\s+(.+?)\s+FROM\s+`([^`]+)`\s*(?:WHERE\s+(.+?))?\s*(?:LIMIT\s+(\d+))?\s*$/i.exec(
+			sql,
+		);
+	if (match === null) return undefined;
+	const [, rawCols, table, rawWhere, rawLimit] = match;
+	if (rawCols === undefined || table === undefined) return undefined;
+	const columns: "*" | string[] =
+		rawCols.trim() === "*"
+			? "*"
+			: rawCols.split(",").map((c) => c.trim().replace(/^`|`$/g, ""));
+	const result: ParsedSelect = { columns, table };
+	if (rawWhere !== undefined) {
+		const clause = rawWhere.trim();
+		// A multi-predicate WHERE (`a` = 1 AND `b` = 2) or an unparseable clause
+		// (non-backtick column, unknown operator) is NOT supported. Return
+		// undefined so the caller throws E_EON_FAKE_UNSUPPORTED rather than
+		// silently dropping the predicate and returning every row (fail-loud).
+		if (hasBooleanConnector(clause)) return undefined;
+		const w = /^`([^`]+)`\s*(=|!=|<>|>=|<=|>|<)\s*(.+)$/.exec(clause);
+		if (
+			w === null ||
+			w[1] === undefined ||
+			w[2] === undefined ||
+			w[3] === undefined
+		) {
+			return undefined;
+		}
+		result.where = {
+			column: w[1],
+			op: w[2],
+			value: parseLiteral(w[3].trim()),
+		};
+	}
+	if (rawLimit !== undefined) result.limit = Number(rawLimit);
+	return result;
+}
+
+/**
+ * True if a WHERE clause has a top-level `AND`/`OR` connector (a multi-predicate
+ * filter the flat store cannot evaluate). Single-quoted string literals are
+ * blanked first so an `AND` inside a value (`'a AND b'`) is not misread.
+ */
+function hasBooleanConnector(clause: string): boolean {
+	const unquoted = clause.replace(/'(?:\\.|[^'\\])*'/g, "''");
+	return /\b(?:AND|OR)\b/i.test(unquoted);
+}
+
+function compareOp(left: unknown, op: string, right: unknown): boolean {
+	switch (op) {
+		case "=":
+			return left === right;
+		case "!=":
+		case "<>":
+			return left !== right;
+		default: {
+			const l = Number(left);
+			const r = Number(right);
+			if (Number.isNaN(l) || Number.isNaN(r)) return false;
+			if (op === ">") return l > r;
+			if (op === ">=") return l >= r;
+			if (op === "<") return l < r;
+			if (op === "<=") return l <= r;
+			return false;
+		}
+	}
+}
+
+/** Split a `VALUES` clause into per-row tuples, respecting quoted strings. */
+function splitTuples(valuesPart: string): string[] {
+	const tuples: string[] = [];
+	let depth = 0;
+	let inString = false;
+	let start = -1;
+	for (let i = 0; i < valuesPart.length; i++) {
+		const ch = valuesPart[i];
+		if (inString) {
+			if (ch === "\\")
+				i++; // skip the escaped char
+			else if (ch === "'") inString = false;
+			continue;
+		}
+		if (ch === "'") {
+			inString = true;
+		} else if (ch === "(") {
+			if (depth === 0) start = i + 1;
+			depth++;
+		} else if (ch === ")") {
+			depth--;
+			if (depth === 0 && start >= 0) {
+				tuples.push(valuesPart.slice(start, i));
+				start = -1;
+			}
+		}
+	}
+	return tuples;
+}
+
+/** Split a tuple body into top-level comma-separated value tokens. */
+function splitValues(tuple: string): string[] {
+	const values: string[] = [];
+	let inString = false;
+	let current = "";
+	for (let i = 0; i < tuple.length; i++) {
+		const ch = tuple[i];
+		if (inString) {
+			current += ch;
+			if (ch === "\\") {
+				const next = tuple[i + 1];
+				if (next !== undefined) {
+					current += next;
+					i++;
+				}
+			} else if (ch === "'") {
+				inString = false;
+			}
+			continue;
+		}
+		if (ch === "'") {
+			inString = true;
+			current += ch;
+		} else if (ch === ",") {
+			values.push(current.trim());
+			current = "";
+		} else {
+			current += ch;
+		}
+	}
+	if (current.trim().length > 0) values.push(current.trim());
+	return values;
+}
+
+/** Parse a single SQL literal token back to a JS value (inverse of `render_literal`). */
+function parseLiteral(token: string): unknown {
+	if (token === "NULL") return null;
+	if (token === "true") return true;
+	if (token === "false") return false;
+	if (token.startsWith("'") && token.endsWith("'")) {
+		return token.slice(1, -1).replace(/\\(['\\])/g, "$1");
+	}
+	const num = Number(token);
+	return Number.isNaN(num) ? token : num;
+}

package/src/testing/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Test helpers for @c9up/eon — the REAL-connection harness for integration
+ * suites (58.2) PLUS the in-memory fake store + factory (58.6).
+ *
+ * `EON_TEST_URL` gates the live paths: unset → local dev without a server, so
+ * 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.
+ */
+
+import { describe } from "vitest";
+import type { EonConnectionConfig } from "../connection/config.js";
+import type { EonConnection } from "../connection/EonConnection.js";
+import { connectWsEon } from "../connection/websocket.js";
+
+export { type FactoryBuilder, factory } from "./Factory.js";
+export { FakeEonConnection } from "./FakeEonConnection.js";
+
+/** The live TDengine URL for integration tests (taosAdapter WS), or `undefined`. */
+function testUrl(): string | undefined {
+	const url = process.env.EON_TEST_URL;
+	return typeof url === "string" && url.length > 0 ? url : undefined;
+}
+
+/** Whether an `EON_TEST_URL` is configured (a live TDengine is reachable). */
+export function hasTestServer(): boolean {
+	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: string, factory: () => void): void {
+	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
+ * with `hasTestServer()` / `describeIfTdengine` first.
+ */
+export function connectTestEon(
+	overrides: Partial<EonConnectionConfig> = {},
+): Promise<EonConnection> {
+	const url = testUrl();
+	if (!url) {
+		throw new Error(
+			"[eon] connectTestEon requires EON_TEST_URL (a live TDengine taosAdapter WS URL, e.g. ws://localhost:6041).",
+		);
+	}
+	return connectWsEon({
+		url,
+		user: "root",
+		password: "taosdata",
+		connectRetries: 10,
+		connectBackoffMs: 250,
+		...overrides,
+	});
+}
+
+/**
+ * Reset a database for test isolation: drop it if present, then recreate it at
+ * millisecond precision. The name is validated against a safe alphabet before
+ * interpolation — a test-only helper, but no injection footgun.
+ */
+export async function resetDatabase(
+	conn: EonConnection,
+	db: string,
+): Promise<void> {
+	if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(db)) {
+		throw new Error(`[eon] resetDatabase: unsafe database name '${db}'`);
+	}
+	await conn.exec(`DROP DATABASE IF EXISTS ${db}`);
+	await conn.exec(`CREATE DATABASE ${db} PRECISION 'ms'`);
+}