@c9up/eon 0.1.0

package/README.md

@@ -0,0 +1,69 @@
+# @c9up/eon
+
+Time-series ORM for Node.js, backed by [TDengine](https://tdengine.com). AdonisJS/Lucid-shaped decorators, a fluent windowed query builder, and injection-safe SQL compiled in Rust.
+
+## Usage
+
+Model a super-table declaratively — the same way you model an Atlas entity, plus a `@Tag` decorator for TDengine's tag columns:
+
+```typescript
+import { SuperTable, Timestamp, Column, Tag } from '@c9up/eon'
+
+@SuperTable('meters')
+class Meter {
+  @Timestamp() declare ts: bigint
+  @Column({ type: 'float' }) declare current: number
+  @Column({ type: 'int' }) declare voltage: number
+  @Tag({ type: 'int' }) declare groupId: number
+  @Tag({ type: 'nchar', length: 24 }) declare location: string
+}
+```
+
+Write points through the repository. Child tables are created automatically from each tag set on first insert:
+
+```typescript
+import { SuperTableRepository } from '@c9up/eon'
+
+const meters = new SuperTableRepository(Meter, connection)
+
+await meters.ingest({ ts: 1700000000000n, current: 10.3, voltage: 219, groupId: 2, location: 'SF' })
+await meters.ingestMany(points)          // columnar STMT bulk — the default high-throughput path
+```
+
+Read with a fluent, windowed query builder (Lucid-shaped, plus TDengine's time-window clauses):
+
+```typescript
+const rows = await meters.query()
+  .select([{ pseudo: '_wstart' }, { function: 'avg', column: 'voltage', alias: 'avgV' }])
+  .whereBetween('ts', [start, end])
+  .partitionBy('groupId')
+  .interval('1m')
+  .fill('prev')
+  .orderBy('_wstart', 'asc')
+  .limit(100)                            // thenable — `await` runs it
+```
+
+## Features
+
+- **Decorators** — `@SuperTable`, `@Timestamp`, `@Column`, `@Tag`; metadata-driven schema (`syncSuperTable`, `createChildTable`, `dropSuperTable`) compiled to real TDengine DDL.
+- **Three ingest paths** — `ingestMany` (columnar STMT, default), `ingestSchemaless` (InfluxDB line protocol), `ingestSql` (literal INSERT). Child tables auto-created per tag set.
+- **Windowed query builder** — `where` / `whereBetween` / `select` (functions + `_wstart` / `_wend` / `_wduration` pseudo-columns) / `partitionBy` / `interval` / `sliding` / `fill` / `orderBy` / `limit` / `offset`; thenable; `query(mapPoint)` for typed rows.
+- **Injection-safe by construction** — every identifier and value is compiled and escaped in a Rust `eon-query` core (NAPI); TypeScript never string-builds SQL.
+- **ws-first transport** over `@tdengine/websocket`, with an `EonProvider` boot/shutdown lifecycle and container-token singletons (`eon`, `eon.connection`, `eon:<name>`).
+- **Precision-safe** — nanosecond timestamps and `BIGINT` columns cross the JSON/NAPI boundary and hydrate as `bigint`, never a lossy `number`.
+
+## Subpath exports
+
+- `@c9up/eon` — decorators, repository, query builder, schema helpers, `compileStatementNative`.
+- `@c9up/eon/provider` — `EonProvider` (default export) for the Ream container.
+- `@c9up/eon/services/connection` — the module-level connection singleton.
+- `@c9up/eon/testing` — test helpers.
+
+## Pinned versions
+
+- TDengine server: `3.3.6.13`
+- `@tdengine/websocket`: `3.5.0`
+
+## License
+
+MIT

package/dist/EonProvider.d.ts

@@ -0,0 +1,51 @@
+/**
+ * EonProvider — Ream provider for the Eon time-series layer.
+ *
+ * On boot it opens the configured ws-first TDengine connection(s) via
+ * `connectWsEon` and registers them in the container (`eon` / `eon.connection`
+ * / `eon:<name>`), plus the module-level `services/connection` singleton. The
+ * transport-independent compiler is registered under `eon.compiler`. Shutdown
+ * closes every connection (fail-open) and releases the singletons.
+ *
+ * Agnostic leaf: consumes the host framework's app context STRUCTURALLY — it
+ * never imports `@c9up/ream`. Any context exposing `config.get(key)` and
+ * `container.singleton(token, factory)` satisfies the contract.
+ */
+import type { EonConnectionConfig } from "./connection/config.js";
+import type { EonConnection } from "./connection/EonConnection.js";
+import { type CompiledStatement, type EonDialect } from "./query/native.js";
+/**
+ * Structural slice of the host framework's app context — only the surface
+ * EonProvider uses. Mirrors atlas `AtlasAppContext`. The `token` type mirrors
+ * ream's `ServiceToken` union so this can grow into Symbol/ctor tokens without
+ * re-coupling to `@c9up/ream`; EonProvider uses `string` tokens today.
+ */
+export interface EonAppContext {
+    container: {
+        singleton(token: string | symbol | (new (...args: never[]) => unknown), factory: () => unknown): void;
+    };
+    config: {
+        get<T = unknown>(key: string): T | undefined;
+    };
+}
+/**
+ * The transport-independent compiler service registered under `eon.compiler`.
+ */
+export interface EonService {
+    compile(spec: object, dialect?: EonDialect): CompiledStatement;
+}
+/**
+ * How EonProvider opens a connection. Defaults to `connectWsEon`; tests inject a
+ * fake so the boot/shutdown wiring is exercised without a live TDengine server
+ * (eon has no in-process transport, unlike atlas's sqlite).
+ */
+export type EonConnector = (config: EonConnectionConfig) => Promise<EonConnection>;
+export declare class EonProvider {
+    #private;
+    constructor(app: EonAppContext, connect?: EonConnector);
+    register(): void;
+    boot(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export default EonProvider;
+//# sourceMappingURL=EonProvider.d.ts.map

package/dist/EonProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EonProvider.d.ts","sourceRoot":"","sources":["../src/EonProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAa,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAC7E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,EACN,KAAK,iBAAiB,EAEtB,KAAK,UAAU,EACf,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,SAAS,EAAE;QACV,SAAS,CACR,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,EAC5D,OAAO,EAAE,MAAM,OAAO,GACpB,IAAI,CAAC;KACR,CAAC;IACF,MAAM,EAAE;QAAE,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAA;KAAE,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IAC1B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,iBAAiB,CAAC;CAC/D;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,CAC1B,MAAM,EAAE,mBAAmB,KACvB,OAAO,CAAC,aAAa,CAAC,CAAC;AAE5B,qBAAa,WAAW;;gBAQX,GAAG,EAAE,aAAa,EAAE,OAAO,GAAE,YAA2B;IAKpE,QAAQ,IAAI,IAAI;IAEV,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAuFrB,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CA4D/B;AAID,eAAe,WAAW,CAAC"}

package/dist/EonProvider.js

@@ -0,0 +1,154 @@
+/**
+ * EonProvider — Ream provider for the Eon time-series layer.
+ *
+ * On boot it opens the configured ws-first TDengine connection(s) via
+ * `connectWsEon` and registers them in the container (`eon` / `eon.connection`
+ * / `eon:<name>`), plus the module-level `services/connection` singleton. The
+ * transport-independent compiler is registered under `eon.compiler`. Shutdown
+ * closes every connection (fail-open) and releases the singletons.
+ *
+ * Agnostic leaf: consumes the host framework's app context STRUCTURALLY — it
+ * never imports `@c9up/ream`. Any context exposing `config.get(key)` and
+ * `container.singleton(token, factory)` satisfies the contract.
+ */
+import { connectWsEon } from "./connection/websocket.js";
+import { compileStatementNative, } from "./query/native.js";
+export class EonProvider {
+    #app;
+    #connect;
+    /** connection name → open connection. Populated at boot. */
+    #connections = new Map();
+    /** Set once a full boot opened connections — guards against a leaking re-boot. */
+    #booted = false;
+    constructor(app, connect = connectWsEon) {
+        this.#app = app;
+        this.#connect = connect;
+    }
+    register() { }
+    async boot() {
+        if (this.#booted) {
+            throw new Error("EonProvider: boot() has already opened connections; a second boot would overwrite and leak them. Call shutdown() first, or construct a new provider.");
+        }
+        // The compiler is transport-independent — register it unconditionally.
+        const service = {
+            compile: (spec, dialect) => compileStatementNative(spec, dialect),
+        };
+        this.#app.container.singleton("eon.compiler", () => service);
+        const config = this.#app.config.get("timeseries") ??
+            this.#app.config.get("eon");
+        if (!config)
+            return;
+        const { connections, defaultName } = this.#resolveConnections(config);
+        // Open every connection in parallel. `allSettled` lets us distinguish
+        // successes from failures without leaking the already-opened ones: on any
+        // failure we close every success before rethrowing (no partial-boot leak).
+        const entries = Object.entries(connections);
+        const results = await Promise.allSettled(entries.map(([, settings]) => this.#connect(settings)));
+        const failures = [];
+        const successes = [];
+        results.forEach((result, i) => {
+            const entry = entries[i];
+            if (!entry)
+                return; // unreachable — allSettled preserves length/order
+            const [name] = entry;
+            if (result.status === "fulfilled") {
+                successes.push({ name, conn: result.value });
+            }
+            else {
+                failures.push({ name, error: result.reason });
+            }
+        });
+        const first = failures[0];
+        if (first) {
+            await Promise.allSettled(successes.map((s) => s.conn.close()));
+            const others = failures
+                .slice(1)
+                .map((f) => `${f.name}: ${String(f.error)}`)
+                .join("; ");
+            throw new Error(`EonProvider: failed to open ${failures.length} connection(s) — ` +
+                `'${first.name}' failed: ${String(first.error)}` +
+                (others ? ` (also: ${others})` : ""));
+        }
+        for (const { name, conn } of successes) {
+            this.#connections.set(name, conn);
+        }
+        const defaultConn = this.#connections.get(defaultName);
+        if (!defaultConn) {
+            // Same rollback the connect-failure branch does above — close the
+            // already-opened sockets before throwing, else they leak (and #booted
+            // stays false, so a retry would open even more).
+            await Promise.allSettled([...this.#connections.values()].map((conn) => conn.close()));
+            this.#connections.clear();
+            throw new Error(`EonProvider: default connection '${defaultName}' is not defined in config.timeseries.connections`);
+        }
+        // Register the container singletons only AFTER validation succeeds. The
+        // throw path above registers none, so a failed boot never leaves an
+        // `eon:<name>` factory resolving to a now-closed connection.
+        for (const { name, conn } of successes) {
+            this.#app.container.singleton(`eon:${name}`, () => conn);
+        }
+        this.#app.container.singleton("eon", () => defaultConn);
+        this.#app.container.singleton("eon.connection", () => defaultConn);
+        // Populate the `@c9up/eon/services/connection` singleton so apps can
+        // `import connection from '@c9up/eon/services/connection'` anywhere. Lazy
+        // import so a type-only discovery scan does not pull the module at
+        // construction time.
+        const { setConnection } = await import("./services/connection.js");
+        setConnection(defaultConn);
+        this.#booted = true;
+    }
+    async shutdown() {
+        // Close every connection in parallel. `allSettled` (fail-open) so a single
+        // stuck close doesn't block the rest, but failures are aggregated and
+        // rethrown so supervisors see a non-zero shutdown signal. The map + module
+        // singleton are cleared unconditionally (never hand out closed handles).
+        const named = [...this.#connections.entries()];
+        const results = await Promise.allSettled(named.map(([, c]) => c.close()));
+        this.#connections.clear();
+        this.#booted = false; // allow a fresh boot() after a clean shutdown
+        const { clearConnection } = await import("./services/connection.js");
+        for (const [, conn] of named)
+            clearConnection(conn);
+        const errors = results
+            .map((result, i) => result.status === "rejected"
+            ? { name: named[i]?.[0] ?? "unknown", error: result.reason }
+            : null)
+            .filter((x) => x !== null);
+        if (errors.length > 0) {
+            const summary = errors
+                .map((e) => `'${e.name}': ${String(e.error)}`)
+                .join("; ");
+            throw new AggregateError(errors.map((e) => e.error), `EonProvider: ${errors.length} connection(s) failed to close — ${summary}`);
+        }
+    }
+    /** Normalize the config into a `{ name → EonConnectionConfig }` map + default name. */
+    #resolveConnections(config) {
+        if (config.connections && Object.keys(config.connections).length > 0) {
+            return {
+                connections: config.connections,
+                defaultName: config.default ?? "primary",
+            };
+        }
+        // Single-connection shape — promote to a one-entry map under "primary"
+        // (mirror atlas: copy the connection fields, drop `default`/`connections`).
+        return {
+            connections: {
+                primary: {
+                    url: config.url,
+                    user: config.user,
+                    password: config.password,
+                    database: config.database,
+                    token: config.token,
+                    timeoutMs: config.timeoutMs,
+                    connectRetries: config.connectRetries,
+                    connectBackoffMs: config.connectBackoffMs,
+                },
+            },
+            defaultName: "primary",
+        };
+    }
+}
+// ream's provider loader constructs `new mod.default(app)` (atlas parity:
+// `export default class AtlasProvider`). The named export stays for tests.
+export default EonProvider;
+//# sourceMappingURL=EonProvider.js.map

package/dist/EonProvider.js.map

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

package/dist/connection/EonConnection.d.ts

@@ -0,0 +1,116 @@
+/**
+ * `EonConnection` — the transport-agnostic seam every eon transport satisfies.
+ *
+ * The WebSocket implementation (`connectWsEon`) is ONE implementation. A
+ * deferred native `taos` implementation (`connectNativeEon`, opt-in, a later
+ * story — memory `project_eon_transport_decision`) satisfies this same
+ * interface, and the locked columnar bulk-ingest STMT method (spike 58-0 AC4)
+ * is added onto a live connection in story 58.4. Neither is built here, but the
+ * seam must not preclude them — keep `exec`/`query`/`ping`/`close`
+ * transport-neutral (no ws-specific type leaks through).
+ *
+ * `exec`/`query` take LITERAL SQL only. TDengine binds positional `?`
+ * placeholders exclusively through the STMT path (58.4 ingest), so the 58.1
+ * compiler's `params` array is NOT threaded through `exec`: a compiled
+ * param-free statement runs as literal SQL, a parameterised one waits for STMT.
+ */
+export interface EonConnection {
+    /**
+     * Which transport backs this connection. A future native impl reports
+     * `"native"`; the in-memory test double (`FakeEonConnection`, 58.6) reports
+     * `"fake"`.
+     */
+    readonly transport: "websocket" | "native" | "fake";
+    /** Run a literal DDL/DML statement (CREATE / USE / INSERT). */
+    exec(sql: string): Promise<{
+        rowsAffected: number;
+    }>;
+    /** Run a literal SELECT; rows are mapped to objects keyed by column name. */
+    query<T = Record<string, unknown>>(sql: string): Promise<T[]>;
+    /** Liveness probe — a cheap round-trip to the server. */
+    ping(): Promise<void>;
+    /**
+     * Columnar STMT bulk ingest (story 58.4) — the default high-throughput write
+     * path. Binds each child table's whole-column typed arrays once per batch
+     * through the transport's STMT2 API, so no per-row object crosses the
+     * boundary (the locked 58.0 columnar contract, kept even on the ws path).
+     *
+     * It lives on the connection — not as a free function — because only the
+     * transport owns the live STMT handle; the `transport` discriminant is a
+     * string, never the raw ws socket. A future native impl satisfies this same
+     * agnostic contract, so ingest code never imports a ws-specific type.
+     */
+    ingestColumnar(request: EonColumnarIngest): Promise<{
+        rowsAffected: number;
+    }>;
+    /**
+     * Schemaless line-protocol ingest (InfluxDB / OpenTSDB). A documented ~8–10×
+     * slower helper than STMT — NOT the default bulk path (AC4). Bypasses SQL
+     * entirely; the transport maps the agnostic protocol/precision to its native
+     * enums.
+     */
+    schemaless(lines: readonly string[], options?: EonSchemalessOptions): Promise<void>;
+    /** Close THIS connection (never the process-global connector — D6). */
+    close(): Promise<void>;
+}
+/**
+ * How a bound column's values are typed for the STMT columnar bind path. Mirrors
+ * the compiler's `ColumnTypeKind` (camelCase) so ingest code carries the column
+ * metadata kind straight through; the transport maps each kind to its native
+ * columnar setter. No ws-specific type leaks into this seam.
+ */
+export type EonBindKind = "timestamp" | "bool" | "tinyInt" | "smallInt" | "int" | "bigInt" | "float" | "double" | "varchar" | "nchar" | "varbinary" | "json" | "decimal";
+/**
+ * One column's values in struct-of-arrays layout plus the kind that selects the
+ * transport's typed setter. `values` holds the WHOLE column (N rows) for metric
+ * columns, or a single-element array for a child's tag value.
+ */
+export interface EonBoundColumn {
+    readonly kind: EonBindKind;
+    readonly values: unknown[];
+}
+/** One child table's columnar batch: its name, tag values, and metric columns. */
+export interface EonChildBatch {
+    /** The (deterministic) child-table name bound via the STMT `?` table slot. */
+    readonly table: string;
+    /** Tag values (one single-element column per tag), bound before the columns. */
+    readonly tags: readonly EonBoundColumn[];
+    /** Value columns in prepared order (timestamp first); each holds the column. */
+    readonly columns: readonly EonBoundColumn[];
+}
+/**
+ * A columnar STMT bulk-ingest request: one prepared template reused across every
+ * child batch. `sql` is the compiler-produced STMT template
+ * (`INSERT INTO ? USING <stable> (…) TAGS (?) VALUES (?)`).
+ */
+export interface EonColumnarIngest {
+    readonly sql: string;
+    readonly children: readonly EonChildBatch[];
+}
+/** Line-protocol variants for the schemaless path. */
+export type EonLineProtocol = "influxdb" | "opentsdb-telnet" | "opentsdb-json";
+/** Timestamp precision for the schemaless path. */
+export type EonSchemalessPrecision = "hours" | "minutes" | "seconds" | "milliseconds" | "microseconds" | "nanoseconds";
+/** Options for {@link EonConnection.schemaless}. */
+export interface EonSchemalessOptions {
+    /** Line-protocol variant. Default `"influxdb"`. */
+    readonly protocol?: EonLineProtocol;
+    /** Timestamp precision. Default `"milliseconds"`. */
+    readonly precision?: EonSchemalessPrecision;
+    /** Child-table TTL in days (0 = none). Default `0`. */
+    readonly ttl?: number;
+}
+/**
+ * Error thrown by an eon transport. When the failure originated in the TDengine
+ * connector, `code` carries the connector's numeric error code verbatim (never
+ * swallowed), so callers can branch on it.
+ */
+export declare class EonConnectionError 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=EonConnection.d.ts.map

package/dist/connection/EonConnection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EonConnection.d.ts","sourceRoot":"","sources":["../../src/connection/EonConnection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IACpD,+DAA+D;IAC/D,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,6EAA6E;IAC7E,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAC9D,yDAAyD;IACzD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;;;;;;;;OAUG;IACH,cAAc,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC9E;;;;;OAKG;IACH,UAAU,CACT,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,uEAAuE;IACvE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GACpB,WAAW,GACX,MAAM,GACN,SAAS,GACT,UAAU,GACV,KAAK,GACL,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,SAAS,GACT,OAAO,GACP,WAAW,GACX,MAAM,GACN,SAAS,CAAC;AAEb;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;CAC3B;AAED,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,CAAC;IACzC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CAC5C;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IACjC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED,sDAAsD;AACtD,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,iBAAiB,GAAG,eAAe,CAAC;AAE/E,mDAAmD;AACnD,MAAM,MAAM,sBAAsB,GAC/B,OAAO,GACP,SAAS,GACT,SAAS,GACT,cAAc,GACd,cAAc,GACd,aAAa,CAAC;AAEjB,oDAAoD;AACpD,MAAM,WAAW,oBAAoB;IACpC,mDAAmD;IACnD,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;IAC5C,uDAAuD;IACvD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC5C,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/connection/EonConnection.js

@@ -0,0 +1,15 @@
+/**
+ * Error thrown by an eon transport. When the failure originated in the TDengine
+ * connector, `code` carries the connector's numeric error code verbatim (never
+ * swallowed), so callers can branch on it.
+ */
+export class EonConnectionError 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 = "EonConnectionError";
+        this.code = options?.code;
+    }
+}
+//# sourceMappingURL=EonConnection.js.map

package/dist/connection/EonConnection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EonConnection.js","sourceRoot":"","sources":["../../src/connection/EonConnection.ts"],"names":[],"mappings":"AAgIA;;;;GAIG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC5C,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,oBAAoB,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,CAAC;IAC3B,CAAC;CACD"}

package/dist/connection/config.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Eon connection configuration — mirrors atlas `ConnectionConfig` /
+ * `AtlasDatabaseConfig` (`AtlasProvider.ts`), adapted for the ws-first TDengine
+ * transport: pool sizing / pragmas / migrations / schema-verification are
+ * dropped (no pool — D7); URL + auth + a connect-retry knob remain.
+ *
+ * No env-var reading happens here: the host `config.get("timeseries")` supplies
+ * the resolved object (agnostic leaf — eon never touches `process.env`).
+ */
+/** One TDengine connection's settings. */
+export interface EonConnectionConfig {
+    /** taosAdapter WebSocket URL, e.g. `ws://localhost:6041`. */
+    url: string;
+    /** Auth user — supplied to the connector via a setter, never embedded in the URL. */
+    user?: string;
+    /** Auth password. */
+    password?: string;
+    /** Default database to `USE` on connect. */
+    database?: string;
+    /** Cloud / bearer token auth (taosAdapter) — alternative to user/password. */
+    token?: string;
+    /**
+     * Per-request timeout in ms, passed to `WSConfig.setTimeOut`. Also used as the
+     * overall connect deadline (a stalled WS handshake rejects instead of wedging
+     * boot). Unset → no JS-side connect deadline.
+     */
+    timeoutMs?: number;
+    /**
+     * Retry the INITIAL connection if it fails — covers a server that starts a
+     * moment after the app (docker-compose / k8s cold start). Extra attempts
+     * beyond the first (default 0 — single attempt). Not a per-query reconnect
+     * (D7: one long-lived connection, no pool).
+     */
+    connectRetries?: number;
+    /** Base backoff in ms between connect attempts (exponential, capped 30s; default 200). */
+    connectBackoffMs?: number;
+}
+/**
+ * Full eon config — single-connection OR multi-connection (atlas parity).
+ *
+ * 58.2 ships single-connection end-to-end; the `default` / `connections` shape
+ * is structural (mirrors atlas) but not yet exercised — named connections /
+ * taosAdapter HA slot behind this same shape in a later story.
+ */
+export interface EonConfig extends EonConnectionConfig {
+    /** Name of the default connection when `connections` is set. Defaults to `"primary"`. */
+    default?: string;
+    /**
+     * Named connections. When present, the top-level `url` is treated as
+     * `connections[default].url`.
+     */
+    connections?: Record<string, EonConnectionConfig>;
+}
+/** Identity helper for typed config authoring — mirrors atlas `defineConfig`. */
+export declare function defineConfig(config: EonConfig): EonConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/connection/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/connection/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IACnC,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,0FAA0F;IAC1F,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,SAAU,SAAQ,mBAAmB;IACrD,yFAAyF;IACzF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;CAClD;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAEzD"}

package/dist/connection/config.js

@@ -0,0 +1,14 @@
+/**
+ * Eon connection configuration — mirrors atlas `ConnectionConfig` /
+ * `AtlasDatabaseConfig` (`AtlasProvider.ts`), adapted for the ws-first TDengine
+ * transport: pool sizing / pragmas / migrations / schema-verification are
+ * dropped (no pool — D7); URL + auth + a connect-retry knob remain.
+ *
+ * No env-var reading happens here: the host `config.get("timeseries")` supplies
+ * the resolved object (agnostic leaf — eon never touches `process.env`).
+ */
+/** Identity helper for typed config authoring — mirrors atlas `defineConfig`. */
+export function defineConfig(config) {
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/connection/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/connection/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgDH,iFAAiF;AACjF,MAAM,UAAU,YAAY,CAAC,MAAiB;IAC7C,OAAO,MAAM,CAAC;AACf,CAAC"}

package/dist/connection/websocket.d.ts

@@ -0,0 +1,16 @@
+/**
+ * WebSocket implementation of `EonConnection` over `@tdengine/websocket` 3.5.0
+ * (ws-only via taosAdapter — no libtaos, no native FFI, D1). The spike-proven
+ * recipe: `WSConfig` + setters → `sqlConnect`; cursor-decode SELECT rows into
+ * column-name-keyed objects; TIMESTAMP / BIGINT stay `BigInt` epoch values (no
+ * lossy `Date` coercion — the consuming ORM layer decides, D4).
+ */
+import type { EonConnectionConfig } from "./config.js";
+import { type EonConnection } from "./EonConnection.js";
+/**
+ * Connect to TDengine over WebSocket and return a transport-agnostic
+ * `EonConnection`. Credentials go through `WSConfig` setters, never embedded in
+ * the URL. The returned object is a single long-lived connection (no pool, D7).
+ */
+export declare function connectWsEon(config: EonConnectionConfig): Promise<EonConnection>;
+//# sourceMappingURL=websocket.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"websocket.d.ts","sourceRoot":"","sources":["../../src/connection/websocket.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAGN,KAAK,aAAa,EAKlB,MAAM,oBAAoB,CAAC;AA8M5B;;;;GAIG;AACH,wBAAsB,YAAY,CACjC,MAAM,EAAE,mBAAmB,GACzB,OAAO,CAAC,aAAa,CAAC,CAkMxB"}