@c9up/eon 0.1.0 → 0.2.0

package/dist/tmq/websocket.js

@@ -0,0 +1,189 @@
+/**
+ * WebSocket implementation of {@link EonConsumer}, over `@tdengine/websocket`'s
+ * `WsConsumer` (ws-only via taosAdapter, like the SQL connection).
+ *
+ * Thin by design: the driver already speaks TMQ. What this adds is the seam
+ * (no ws type leaks out), decoded rows instead of a `TaosResult`, one error
+ * type, and two defaults chosen for safety rather than convenience — see
+ * `autoCommit` and `offsetReset`.
+ */
+import { TDWebSocketClientError, TMQConstants, WsConsumer, } from "@tdengine/websocket";
+import { EonConsumerError, } from "./EonConsumer.js";
+function wrapError(cause, message) {
+    if (cause instanceof TDWebSocketClientError) {
+        return new EonConsumerError(`${message}: ${cause.message}`, {
+            cause,
+            code: cause.code,
+        });
+    }
+    return new EonConsumerError(message, { cause });
+}
+/** Zip a poll result's column metadata with its rows. */
+function decode(result) {
+    const meta = result.getMeta() ?? [];
+    const data = result.getData() ?? [];
+    if (data.length > 0 && meta.length === 0) {
+        // The same trap the query decoder guards: rows with no column metadata
+        // would each decode to `{}` — silent data loss. Fail loud.
+        throw new EonConsumerError(`[E_EON_DECODE] poll returned rows but no column metadata for topic '${result.getTopic()}'; cannot decode`);
+    }
+    return data.map((row) => {
+        const record = {};
+        meta.forEach((column, index) => {
+            record[column.name] = row[index];
+        });
+        return record;
+    });
+}
+function toPartition(p) {
+    return {
+        topic: p.topic,
+        vgroupId: p.vgroup_id,
+        offset: p.offset,
+        begin: p.begin,
+        end: p.end,
+    };
+}
+/**
+ * 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 async function connectWsConsumer(config) {
+    const options = new Map([
+        [TMQConstants.WS_URL, config.url],
+        [TMQConstants.GROUP_ID, config.groupId],
+        [TMQConstants.AUTO_OFFSET_RESET, config.offsetReset ?? "latest"],
+        [
+            TMQConstants.ENABLE_AUTO_COMMIT,
+            config.autoCommit === true ? "true" : "false",
+        ],
+        [
+            TMQConstants.MSG_WITH_TABLE_NAME,
+            config.withTableName === false ? "false" : "true",
+        ],
+    ]);
+    if (config.clientId)
+        options.set(TMQConstants.CLIENT_ID, config.clientId);
+    if (config.user)
+        options.set(TMQConstants.CONNECT_USER, config.user);
+    if (config.password)
+        options.set(TMQConstants.CONNECT_PASS, config.password);
+    if (config.token)
+        options.set(TMQConstants.CONNECT_TOKEN, config.token);
+    if (config.autoCommit === true && config.autoCommitIntervalMs !== undefined) {
+        options.set(TMQConstants.AUTO_COMMIT_INTERVAL_MS, String(config.autoCommitIntervalMs));
+    }
+    let consumer;
+    try {
+        consumer = await WsConsumer.newConsumer(options);
+    }
+    catch (error) {
+        throw wrapError(error, `eon: failed to open a consumer on '${config.url}'`);
+    }
+    let closed = false;
+    function ensureOpen() {
+        if (closed) {
+            throw new EonConsumerError("eon: consumer is closed");
+        }
+    }
+    return {
+        async subscribe(topics) {
+            ensureOpen();
+            if (topics.length === 0) {
+                // An empty subscribe is accepted by the server and then delivers
+                // nothing forever — a silent no-op is the worst possible answer.
+                throw new EonConsumerError("eon: subscribe() needs at least one topic");
+            }
+            try {
+                await consumer.subscribe(topics);
+            }
+            catch (error) {
+                throw wrapError(error, `eon: subscribe failed for [${topics.join(", ")}]`);
+            }
+        },
+        async subscription() {
+            ensureOpen();
+            try {
+                return await consumer.subscription();
+            }
+            catch (error) {
+                throw wrapError(error, "eon: reading the subscription failed");
+            }
+        },
+        async poll(timeoutMs) {
+            ensureOpen();
+            let polled;
+            try {
+                polled = await consumer.poll(timeoutMs);
+            }
+            catch (error) {
+                throw wrapError(error, "eon: poll failed");
+            }
+            const out = [];
+            for (const [topic, result] of polled) {
+                out.push({ topic, rows: decode(result) });
+            }
+            return out;
+        },
+        async commit() {
+            ensureOpen();
+            try {
+                return (await consumer.commit()).map(toPartition);
+            }
+            catch (error) {
+                throw wrapError(error, "eon: commit failed");
+            }
+        },
+        async assignment(topics) {
+            ensureOpen();
+            try {
+                return (await consumer.assignment(topics)).map(toPartition);
+            }
+            catch (error) {
+                throw wrapError(error, "eon: reading the assignment failed");
+            }
+        },
+        async seek(partition) {
+            ensureOpen();
+            if (partition.offset === undefined) {
+                throw new EonConsumerError("eon: seek() needs an offset");
+            }
+            try {
+                await consumer.seek({
+                    topic: partition.topic,
+                    vgroup_id: partition.vgroupId,
+                    offset: partition.offset,
+                });
+            }
+            catch (error) {
+                throw wrapError(error, `eon: seek failed on '${partition.topic}'`);
+            }
+        },
+        async unsubscribe() {
+            ensureOpen();
+            try {
+                await consumer.unsubscribe();
+            }
+            catch (error) {
+                throw wrapError(error, "eon: unsubscribe failed");
+            }
+        },
+        async close() {
+            // Idempotent: a `finally` that closes twice must not throw.
+            if (closed)
+                return;
+            closed = true;
+            try {
+                await consumer.close();
+            }
+            catch (error) {
+                throw wrapError(error, "eon: closing the consumer failed");
+            }
+        },
+    };
+}
+//# sourceMappingURL=websocket.js.map

package/dist/tmq/websocket.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@c9up/eon",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Eon — time-series data layer for the Ream framework (TDengine-backed)",
   "license": "MIT",
   "type": "module",
@@ -38,9 +38,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
+    "@types/node": "^22",
+    "tsx": "^4.19.0",
     "typescript": "^6.0.2",
-    "vitest": "^4.1.2",
-    "@types/node": "^22"
+    "vitest": "^4.1.2"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -52,6 +53,14 @@
     "type": "git",
     "url": "git+https://github.com/C9up/eon.git"
   },
+  "peerDependencies": {
+    "vitest": ">=3"
+  },
+  "peerDependenciesMeta": {
+    "vitest": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
     "build:rust": "cargo build --release -p eon-query-napi",

package/src/EonProvider.ts

@@ -33,6 +33,14 @@ export interface EonAppContext {
 			token: string | symbol | (new (...args: never[]) => unknown),
 			factory: () => unknown,
 		): void;
+		/**
+		 * Optional reader — present on ream's real container. Used to look up the
+		 * `migrations` registry so `ream migrate` can drive eon without naming it.
+		 * Structural, async-capable, like the binder above.
+		 */
+		resolve?(
+			token: string | symbol | (new (...args: never[]) => unknown),
+		): unknown | Promise<unknown>;
 	};
 	config: { get<T = unknown>(key: string): T | undefined };
 }
@@ -152,9 +160,53 @@ export class EonProvider {
 		// construction time.
 		const { setConnection } = await import("./services/connection.js");
 		setConnection(defaultConn);
+
+		await this.#registerMigrationSource(defaultConn, config);
 		this.#booted = true;
 	}
 
+	/**
+	 * Hand eon's migration runner to the framework's `migrations` registry, so
+	 * `ream migrate` drives it without the CLI knowing eon exists.
+	 *
+	 * Best-effort and duck-typed: eon does not import `@c9up/ream`, and a host
+	 * with no registry (an older ream, or another framework) must still boot.
+	 * The CLI is where a missing registry gets reported, because that is where
+	 * the user can act on it.
+	 */
+	async #registerMigrationSource(
+		conn: EonConnection,
+		config: EonConfig,
+	): Promise<void> {
+		const resolve = this.#app.container.resolve;
+		if (typeof resolve !== "function") return;
+
+		let registry: unknown;
+		try {
+			registry = await resolve.call(this.#app.container, "migrations");
+		} catch {
+			return;
+		}
+		if (
+			typeof registry !== "object" ||
+			registry === null ||
+			!("register" in registry) ||
+			typeof registry.register !== "function"
+		) {
+			return;
+		}
+
+		const { EonMigrationRunner } = await import(
+			"./schema/EonMigrationRunner.js"
+		);
+		const migrationsDir = config.migrationsDir ?? "database/eon-migrations";
+		(registry.register as (source: unknown) => unknown)({
+			name: "eon",
+			directory: migrationsDir,
+			runner: new EonMigrationRunner(conn, { migrationsDir }),
+		});
+	}
+
 	async shutdown(): Promise<void> {
 		// Close every connection in parallel. `allSettled` (fail-open) so a single
 		// stuck close doesn't block the rest, but failures are aggregated and
@@ -168,6 +220,15 @@ export class EonProvider {
 		const { clearConnection } = await import("./services/connection.js");
 		for (const [, conn] of named) clearConnection(conn);
 
+		// Closing every connection is NOT enough to let Node exit: the connector
+		// keeps process-global handles, so a service that shut down cleanly would
+		// hang forever. Only for a real ws connection — a fake-only boot (tests)
+		// must not pull the connector in. Dynamic import for the same reason.
+		if (named.some(([, c]) => c.transport === "websocket")) {
+			const { destroyEonConnector } = await import("./connection/websocket.js");
+			await destroyEonConnector();
+		}
+
 		const errors = results
 			.map((result, i) =>
 				result.status === "rejected"

package/src/configure.ts

@@ -0,0 +1,38 @@
+/**
+ * `ream configure @c9up/eon` — wire eon into an app in one command.
+ *
+ * Mirrors atlas's hook: register the provider, seed the env vars, write the
+ * config file. Without it the CLI can only report that eon exports no
+ * configure(), and every app wires eon by hand.
+ */
+interface Codemods {
+	addProvider(importPath: string): Promise<void>;
+	addEnvVars(vars: Record<string, string>): Promise<void>;
+	writeFile(
+		filePath: string,
+		content: string,
+		options?: { force?: boolean },
+	): Promise<void>;
+}
+
+export async function configure(codemods: Codemods): Promise<void> {
+	await codemods.addProvider("@c9up/eon/provider");
+	await codemods.addEnvVars({
+		TDENGINE_URL: "ws://localhost:6041",
+		TDENGINE_USER: "root",
+		TDENGINE_PASSWORD: "taosdata",
+		TDENGINE_DATABASE: "ream",
+	});
+	await codemods.writeFile(
+		"config/timeseries.ts",
+		`import { defineConfig } from '@c9up/eon'
+
+export default defineConfig({
+  url: process.env.TDENGINE_URL ?? 'ws://localhost:6041',
+  user: process.env.TDENGINE_USER ?? 'root',
+  password: process.env.TDENGINE_PASSWORD ?? '',
+  database: process.env.TDENGINE_DATABASE ?? 'ream',
+})
+`,
+	);
+}

package/src/connection/config.ts

@@ -52,6 +52,14 @@ export interface EonConfig extends EonConnectionConfig {
 	 * `connections[default].url`.
 	 */
 	connections?: Record<string, EonConnectionConfig>;
+	/**
+	 * Where eon's migration files live, relative to the app root.
+	 *
+	 * Separate from atlas's `database/migrations`: the two stores migrate
+	 * independently, and one directory holding both would hand every file to
+	 * both runners. Default: `database/eon-migrations`.
+	 */
+	migrationsDir?: string;
 }
 
 /** Identity helper for typed config authoring — mirrors atlas `defineConfig`. */

package/src/connection/websocket.ts

@@ -7,6 +7,7 @@
  */
 
 import {
+	destroy,
 	Precision,
 	SchemalessProto,
 	type StmtBindParams,
@@ -232,6 +233,22 @@ async function connectWithRetry(config: EonConnectionConfig): Promise<WsSql> {
 	);
 }
 
+/**
+ * Tear down the connector's PROCESS-GLOBAL resources.
+ *
+ * `EonConnection.close()` closes one connection and deliberately leaves this
+ * alone (D6). But the connector keeps process-wide handles alive, so closing
+ * every connection is NOT enough for Node to exit — a service that shuts down
+ * cleanly would hang forever. Call this once, after the last connection is
+ * closed; `EonProvider.shutdown()` already does.
+ *
+ * Reversible: a later `connectWsEon` reconnects normally (verified against a
+ * live server), so a boot → shutdown → boot cycle is fine.
+ */
+export async function destroyEonConnector(): Promise<void> {
+	await destroy();
+}
+
 /**
  * Connect to TDengine over WebSocket and return a transport-agnostic
  * `EonConnection`. Credentials go through `WSConfig` setters, never embedded in

package/src/health.ts

@@ -0,0 +1,99 @@
+/**
+ * A health check for a TDengine connection.
+ *
+ * Upstream ships one per datastore — `DbConnectionCountCheck` in lucid,
+ * `RedisMemoryUsageCheck` in redis — and ream now has the runner
+ * (`@c9up/ream/health`). This is eon's.
+ *
+ * AGNOSTIC BY CONSTRUCTION — the contract is re-declared here rather than
+ * imported from `@c9up/ream`. eon must not depend on the framework at runtime,
+ * and ream's `HealthChecks` consumes anything of this shape: a `name`, an
+ * optional `cacheDuration`, and a `run()`.
+ */
+import type { EonConnection } from "./connection/EonConnection.js";
+
+/** The result shape ream's health runner consumes. */
+export interface EonHealthResult {
+	message: string;
+	status: "ok" | "warning" | "error";
+	finishedAt: Date;
+	meta?: Record<string, unknown>;
+}
+
+/**
+ * Reports whether the server answers, and how slowly.
+ *
+ * ```ts
+ * healthChecks.register([
+ *   new EonConnectionCheck(conn).warnWhenSlowerThan(250).cacheFor(30),
+ * ])
+ * ```
+ */
+export class EonConnectionCheck {
+	readonly #conn: EonConnection;
+	#warnAfterMs = 500;
+
+	name = "TDengine connection check";
+	/** Seconds to reuse the last result for. A probe every second must not ping every second. */
+	cacheDuration?: number;
+
+	constructor(conn: EonConnection) {
+		this.#conn = conn;
+	}
+
+	/** Rename the check, so two connections stay distinguishable in a report. */
+	as(name: string): this {
+		this.name = name;
+		return this;
+	}
+
+	/** Reuse the last result for this many seconds. */
+	cacheFor(seconds: number): this {
+		this.cacheDuration = seconds;
+		return this;
+	}
+
+	/**
+	 * Warn once a ping takes longer than this.
+	 *
+	 * A reachable-but-slow server is the case worth reporting: it is not down,
+	 * so failing would pull a healthy pod out of rotation, and it is not fine,
+	 * so `ok` would hide the thing an operator needs to see.
+	 */
+	warnWhenSlowerThan(milliseconds: number): this {
+		this.#warnAfterMs = milliseconds;
+		return this;
+	}
+
+	async run(): Promise<EonHealthResult> {
+		const startedAt = Date.now();
+		try {
+			await this.#conn.ping();
+			const latency = Date.now() - startedAt;
+			const meta = { latency, warningThreshold: this.#warnAfterMs };
+			if (latency >= this.#warnAfterMs) {
+				return {
+					status: "warning",
+					message: `TDengine answered in ${latency}ms, above the threshold of ${this.#warnAfterMs}ms`,
+					finishedAt: new Date(),
+					meta,
+				};
+			}
+			return {
+				status: "ok",
+				message: "TDengine is reachable",
+				finishedAt: new Date(),
+				meta,
+			};
+		} catch (error) {
+			return {
+				status: "error",
+				message: "TDengine is unreachable",
+				finishedAt: new Date(),
+				// The error itself, not just its message: a caller that logs the
+				// report keeps the stack, and a dedup key must never be a message.
+				meta: { error, latency: Date.now() - startedAt },
+			};
+		}
+	}
+}

package/src/index.ts

@@ -16,7 +16,10 @@ export {
 	type EonSchemalessOptions,
 	type EonSchemalessPrecision,
 } from "./connection/EonConnection.js";
-export { connectWsEon } from "./connection/websocket.js";
+export {
+	connectWsEon,
+	destroyEonConnector,
+} from "./connection/websocket.js";
 export {
 	Column,
 	type EonColumnMetadata,
@@ -38,6 +41,10 @@ export type {
 	EonService,
 } from "./EonProvider.js";
 export { EonProvider } from "./EonProvider.js";
+export {
+	EonConnectionCheck,
+	type EonHealthResult,
+} from "./health.js";
 export { toLineProtocol } from "./ingest/schemaless.js";
 export { buildLiteralInserts } from "./ingest/sql.js";
 export {
@@ -116,3 +123,12 @@ export {
 	dropSuperTable,
 	syncSuperTable,
 } from "./schema/sync.js";
+export {
+	type EonConsumer,
+	type EonConsumerConfig,
+	EonConsumerError,
+	type EonMessage,
+	type EonOffsetReset,
+	type EonTopicPartition,
+} from "./tmq/EonConsumer.js";
+export { connectWsConsumer } from "./tmq/websocket.js";

package/src/query/TimeSeriesQuery.ts

@@ -302,7 +302,18 @@ export class TimeSeriesQuery<TPoint extends object = Record<string, unknown>>
 		return this;
 	}
 
-	/** `FILL(mode[, ...values])` — requires an `interval`; `values` only for `value` mode. */
+	/**
+	 * `FILL(mode[, ...values])` — requires an `interval`; `values` only for
+	 * `value` mode.
+	 *
+	 * TDengine additionally requires a **bounded time range** alongside `FILL`:
+	 * without one the server answers `9787` ("Start(end) time of query range
+	 * required or time range too large"), because filling gaps has no meaning
+	 * over an unbounded window. Pair it with {@link whereBetween} on the
+	 * timestamp column. Not validated here — the bound may legitimately come
+	 * from any combination of predicates, and rejecting a valid query would be
+	 * worse than the server's own error.
+	 */
 	fill(mode: EonFillMode, ...values: readonly EonScalar[]): this {
 		this.#cachedExec = undefined;
 		this.#fill = { mode, values };