@c9up/eon 0.1.0

package/src/repository/SuperTableRepository.ts

@@ -0,0 +1,347 @@
+/**
+ * `SuperTableRepository<TPoint>` — the Atlas-shaped ingest API for a TDengine
+ * super-table (story 58.4).
+ *
+ * Mirrors `@c9up/atlas` `BaseRepository` naming: `ingest` (≙ `create`) and
+ * `ingestMany` (≙ `createMany`, the bulk primitive), plus two extra write paths
+ * TDengine adds — `ingestSql` (literal INSERT) and `ingestSchemaless` (line
+ * protocol). It deliberately OMITS everything TDengine has no analogue for
+ * (AC8): no `save`/`upsert`/`firstOrCreate`, no `useTransaction`/BEGIN-COMMIT,
+ * no `RETURNING`, no DB-generated-PK hydrate-back. TDengine writes are
+ * append / last-write-wins by the caller-supplied timestamp.
+ *
+ * Schema is read ONLY through the 58.3 decorator metadata getters — never
+ * `key in instance` (the `@Column() declare x` pitfall, memory
+ * `project_atlas_declare_hydration`). The connection is injected structurally
+ * (agnostic leaf, AD1 — no `@c9up/ream` import).
+ */
+
+import type {
+	EonConnection,
+	EonSchemalessOptions,
+} from "../connection/EonConnection.js";
+import {
+	getColumnMetadata,
+	getSuperTableMetadata,
+	getTagMetadata,
+	getTimestampColumn,
+} from "../decorators/superTable.js";
+import { toLineProtocol } from "../ingest/schemaless.js";
+import { buildLiteralInserts } from "../ingest/sql.js";
+import {
+	buildColumnarIngest,
+	type ColumnarPlan,
+	compileStmtTemplate,
+	DEFAULT_BATCH_SIZE,
+	type IngestPoint,
+	type PlanColumn,
+	toBindKind,
+} from "../ingest/stmt.js";
+import { TimeSeriesQuery } from "../query/TimeSeriesQuery.js";
+import {
+	orderTimestampFirst,
+	type SuperTableClass,
+} from "../schema/compile.js";
+
+/** Options for {@link SuperTableRepository}. */
+export interface SuperTableRepositoryOptions {
+	/** STMT chunk size (rows per child per bind). Default {@link DEFAULT_BATCH_SIZE}. */
+	readonly batchSize?: number;
+}
+
+/**
+ * Repository for a TDengine super-table — atlas `BaseRepository` parity for the
+ * time-series model. NAMED deviation from atlas (prime directive: name any
+ * divergence): atlas types reads by constructing `new Entity()` instances; eon
+ * reads plain records and never constructs instances, so typed reads are opt-in
+ * through `query(mapPoint)` — the caller supplies the row → `E` mapper, composed
+ * on top of the bigint/timestamp-reviving base hydrator (no `as`, the decode
+ * stays honest). Called without a mapper, points stay `Record<string, unknown>`.
+ */
+export class SuperTableRepository {
+	readonly #conn: EonConnection;
+	readonly #plan: ColumnarPlan;
+	readonly #querySchema: QuerySchema;
+
+	constructor(
+		entityClass: SuperTableClass,
+		conn: EonConnection,
+		options?: SuperTableRepositoryOptions,
+	) {
+		// Fail loud on a null/undefined connection — almost always a failed IoC
+		// injection (atlas `BaseRepository.ts:245` parity), not a runtime NPE later.
+		if (conn === null || conn === undefined) {
+			throw new Error(
+				`[E_EON_MISSING_CONNECTION] SuperTableRepository for '${entityClass?.name ?? "<unknown entity>"}' requires an EonConnection (got ${conn === null ? "null" : "undefined"}). Check IoC constructor injection is wired.`,
+			);
+		}
+		this.#conn = conn;
+		this.#plan = buildPlan(entityClass, options);
+		this.#querySchema = buildQuerySchema(entityClass);
+	}
+
+	/**
+	 * A fluent time-series read builder bound to this repository's connection and
+	 * the entity's 58.3 schema metadata. Rows hydrate through a metadata-driven
+	 * closure — declared columns by their `@Column`/`@Tag` metadata (bigint /
+	 * timestamp revived as `bigint`), NEVER `key in instance` (the `declare`-field
+	 * pitfall), and window pseudo-columns / aggregate aliases attached raw.
+	 *
+	 * Pass `mapPoint` to project each decoded row into a typed `E` (atlas-parity
+	 * typed reads, no `as`): the mapper composes on top of the base hydrator so
+	 * bigint/timestamp revival still happens first. Without a mapper, points stay
+	 * `Record<string, unknown>`.
+	 */
+	query(): TimeSeriesQuery<Record<string, unknown>>;
+	query<E extends object>(
+		mapPoint: (row: Record<string, unknown>) => E,
+	): TimeSeriesQuery<E>;
+	query<E extends object>(
+		mapPoint?: (row: Record<string, unknown>) => E,
+	): TimeSeriesQuery<E> | TimeSeriesQuery<Record<string, unknown>> {
+		const base = this.#querySchema.hydrate;
+		if (mapPoint) {
+			return new TimeSeriesQuery(
+				this.#querySchema.stable,
+				this.#conn,
+				(row) => mapPoint(base(row)),
+				this.#querySchema.known,
+			);
+		}
+		return new TimeSeriesQuery(
+			this.#querySchema.stable,
+			this.#conn,
+			base,
+			this.#querySchema.known,
+		);
+	}
+
+	/** Ingest a single point (≙ atlas `create`). */
+	async ingest(point: IngestPoint): Promise<void> {
+		await this.ingestMany([point]);
+	}
+
+	/**
+	 * Bulk ingest via the columnar STMT path (≙ atlas `createMany`) — the default
+	 * high-throughput, injection-safe write. Groups by child table, binds SoA
+	 * columns once per batch. Returns total rows affected. `async` so a plan
+	 * error (e.g. an unsafe-integer timestamp) surfaces as a rejection, not a
+	 * synchronous throw at the call site.
+	 */
+	async ingestMany(
+		points: readonly IngestPoint[],
+	): Promise<{ rowsAffected: number }> {
+		if (points.length === 0) return { rowsAffected: 0 };
+		return this.#conn.ingestColumnar(buildColumnarIngest(this.#plan, points));
+	}
+
+	/**
+	 * Bulk ingest via literal SQL INSERT (AC5) — a convenience/fallback path run
+	 * through `exec`. One `INSERT … USING … TAGS … VALUES` per child table; all
+	 * value literals are rendered by the Rust compiler (no TS interpolation).
+	 */
+	async ingestSql(
+		points: readonly IngestPoint[],
+	): Promise<{ rowsAffected: number }> {
+		if (points.length === 0) return { rowsAffected: 0 };
+		let rowsAffected = 0;
+		for (const sql of buildLiteralInserts(this.#plan, points)) {
+			const result = await this.#conn.exec(sql);
+			rowsAffected += result.rowsAffected;
+		}
+		return { rowsAffected };
+	}
+
+	/**
+	 * Bulk ingest via schemaless line protocol (AC4) — a documented ~8–10× slower
+	 * helper, NOT the default bulk path. Renders points to InfluxDB line protocol
+	 * from the entity metadata and passes them to the transport.
+	 */
+	async ingestSchemaless(
+		points: readonly IngestPoint[],
+		options?: EonSchemalessOptions,
+	): Promise<void> {
+		if (points.length === 0) return;
+		await this.#conn.schemaless(toLineProtocol(this.#plan, points), options);
+	}
+}
+
+/** Resolve the immutable ingest plan from a decorated super-table class. */
+function buildPlan(
+	entityClass: SuperTableClass,
+	options?: SuperTableRepositoryOptions,
+): ColumnarPlan {
+	const meta = getSuperTableMetadata(entityClass);
+	if (!meta) {
+		throw new Error(
+			`[E_EON_NOT_A_SUPERTABLE] ${entityClass.name} is not decorated with @SuperTable`,
+		);
+	}
+	const tsProperty = getTimestampColumn(entityClass);
+	if (!tsProperty) {
+		throw new Error(
+			`[E_EON_NO_TIMESTAMP] super-table '${meta.name}' has no @Timestamp column`,
+		);
+	}
+
+	const columnMeta = getColumnMetadata(entityClass);
+	const tsColumn = columnMeta.find((c) => c.propertyKey === tsProperty);
+	if (!tsColumn) {
+		throw new Error(
+			`[E_EON_NO_TIMESTAMP] super-table '${meta.name}' @Timestamp column '${tsProperty}' is not registered`,
+		);
+	}
+	// Timestamp first, from the SAME shared ordering the STABLE was created with
+	// (`orderTimestampFirst`), so the positional STMT bind lines up with the
+	// STABLE's physical columns and can never drift.
+	const ordered = orderTimestampFirst(columnMeta, tsColumn, tsProperty);
+	const columns: PlanColumn[] = ordered.map((c) => ({
+		property: c.propertyKey,
+		kind: toBindKind(c.type, c.propertyKey),
+	}));
+
+	const tags: PlanColumn[] = getTagMetadata(entityClass).map((t) => ({
+		property: t.propertyKey,
+		kind: toBindKind(t.type, t.propertyKey),
+	}));
+	if (tags.length === 0) {
+		throw new Error(
+			`[E_EON_NO_TAGS] super-table '${meta.name}' has no @Tag columns; a child table cannot be routed without tags`,
+		);
+	}
+
+	const batchSize = options?.batchSize ?? DEFAULT_BATCH_SIZE;
+	if (!Number.isInteger(batchSize) || batchSize <= 0) {
+		throw new Error(
+			`[E_EON_BATCH_SIZE] batchSize must be a positive integer (got ${batchSize})`,
+		);
+	}
+
+	const templateSql = compileStmtTemplate(
+		meta.name,
+		tags.map((t) => t.property),
+		columns.map((c) => c.property),
+	);
+
+	return {
+		stable: meta.name,
+		templateSql,
+		tsProperty,
+		columns,
+		tags,
+		batchSize,
+	};
+}
+
+/** The metadata a {@link TimeSeriesQuery} needs to hydrate rows into points. */
+interface QuerySchema {
+	/** The super-table name (FROM target). */
+	readonly stable: string;
+	/** Revive declared columns (bigint/timestamp → `bigint`); skip everything else. */
+	readonly hydrate: (row: Record<string, unknown>) => Record<string, unknown>;
+	/** Declared column + tag property names (used to separate raw window extras). */
+	readonly known: ReadonlySet<string>;
+}
+
+/**
+ * Build the read-side schema from the 58.3 decorator getters. The `@Column`/
+ * `@Tag` metadata is the ONLY source of truth — never `key in instance` (the
+ * `@Column() declare x` pitfall, memory `project_atlas_declare_hydration`).
+ */
+function buildQuerySchema(entityClass: SuperTableClass): QuerySchema {
+	const meta = getSuperTableMetadata(entityClass);
+	if (!meta) {
+		throw new Error(
+			`[E_EON_NOT_A_SUPERTABLE] ${entityClass.name} is not decorated with @SuperTable`,
+		);
+	}
+	const tsProperty = getTimestampColumn(entityClass);
+	if (!tsProperty) {
+		throw new Error(
+			`[E_EON_NO_TIMESTAMP] super-table '${meta.name}' has no @Timestamp column`,
+		);
+	}
+
+	const columns = getColumnMetadata(entityClass);
+	const tags = getTagMetadata(entityClass);
+	const known = new Set<string>([
+		...columns.map((c) => c.propertyKey),
+		...tags.map((t) => t.propertyKey),
+	]);
+	// A column reads back as `bigint` when it is the timestamp primary column or
+	// its logical type is a 64-bit integer — parity with the compile-boundary
+	// precision guard, so a nanosecond `ts` or a BIGINT metric never narrows to a
+	// lossy double.
+	const bigintColumns = new Set<string>();
+	for (const column of columns) {
+		if (column.propertyKey === tsProperty || isBigintLogicalType(column.type)) {
+			bigintColumns.add(column.propertyKey);
+		}
+	}
+	for (const tag of tags) {
+		if (isBigintLogicalType(tag.type)) bigintColumns.add(tag.propertyKey);
+	}
+
+	const hydrate = (row: Record<string, unknown>): Record<string, unknown> => {
+		// Decode by metadata membership, iterating the raw row's own keys — never
+		// `for (key in instance)` (a `declare` field is not an own property).
+		const point: Record<string, unknown> = {};
+		for (const [key, value] of Object.entries(row)) {
+			if (!known.has(key)) continue;
+			// `defineProperty`, not assignment: a column named `__proto__`/`constructor`
+			// would otherwise hit the inherited accessor and re-parent `point`.
+			Object.defineProperty(point, key, {
+				value: bigintColumns.has(key) ? reviveBigInt(value) : value,
+				writable: true,
+				enumerable: true,
+				configurable: true,
+			});
+		}
+		return point;
+	};
+
+	return { stable: meta.name, hydrate, known };
+}
+
+/**
+ * Logical types that read back as 64-bit integers. Matched case-insensitively
+ * and including the `bigInteger` alias, so it stays in lock-step with the DDL /
+ * bind side (`TYPE_KIND_MAP` accepts `bigint`/`bigInteger`/any-case `BIGINT`) —
+ * a divergence here would read a genuine BIGINT column back as a lossy `number`.
+ */
+function isBigintLogicalType(type: string | undefined): boolean {
+	if (type === undefined) return false;
+	const t = type.toLowerCase();
+	return t === "bigint" || t === "biginteger" || t === "timestamp";
+}
+
+/**
+ * Revive a raw column value into a `bigint` for a timestamp / BIGINT column.
+ * Accepts an existing `bigint`, an integer `number`, or an all-digits string;
+ * passes `null`/`undefined` through (a nullable window aggregate). Anything else
+ * — a fractional number, an unexpected type — fails loud rather than silently
+ * narrowing precision.
+ */
+function reviveBigInt(value: unknown): unknown {
+	if (typeof value === "bigint") return value;
+	if (typeof value === "number") {
+		if (!Number.isInteger(value)) {
+			throw new Error(
+				`[E_EON_HYDRATE_BIGINT] expected an integer for a bigint/timestamp column, got the non-integer ${value}`,
+			);
+		}
+		if (!Number.isSafeInteger(value)) {
+			throw new Error(
+				`[E_EON_HYDRATE_BIGINT] integer ${value} exceeds the JS safe-integer range (2^53) and has already lost precision; the transport must hand a bigint/timestamp column back as bigint or a string, not a lossy number`,
+			);
+		}
+		return BigInt(value);
+	}
+	if (typeof value === "string" && /^-?\d+$/.test(value)) {
+		return BigInt(value);
+	}
+	if (value === null || value === undefined) return value;
+	throw new Error(
+		`[E_EON_HYDRATE_BIGINT] cannot revive a bigint/timestamp column from a ${typeof value}`,
+	);
+}

package/src/schema/CreateStableSpec.ts

@@ -0,0 +1,184 @@
+/**
+ * TypeScript spec shapes mirroring the Rust `crates/eon-query/src/ddl.rs`
+ * structs, plus the logical → compiler-kind type map (parallel to atlas
+ * `schema/types.ts`).
+ *
+ * The facade assembles these plain JSON objects from decorator metadata and
+ * hands them to `compileStatementNative`; the Rust compiler owns all quoting,
+ * type-mapping, and schema-rule validation — the TS side never string-builds
+ * SQL (D1, the injection seam stays in Rust).
+ */
+
+/** The user-facing logical type strings accepted on `@Column`/`@Tag`/`@Timestamp`. */
+export type EonLogicalType =
+	| "timestamp"
+	| "int"
+	| "integer"
+	| "bigint"
+	| "biginteger"
+	| "smallint"
+	| "tinyint"
+	| "float"
+	| "double"
+	| "bool"
+	| "boolean"
+	| "string"
+	| "varchar"
+	| "nchar"
+	| "binary"
+	| "varbinary"
+	| "json"
+	| "decimal";
+
+/**
+ * Map a logical type string to the compiler's `ColumnTypeKind` (serde
+ * camelCase). Common aliases collapse onto one kind (`int`/`integer` → `int`,
+ * `string`/`varchar` → `varchar`, `binary`/`varbinary` → `varbinary`). Physical
+ * TDengine types are resolved from these kinds in Rust (`Dialect::map_column_type`).
+ */
+const TYPE_KIND_ENTRIES = {
+	timestamp: "timestamp",
+	int: "int",
+	integer: "int",
+	bigint: "bigInt",
+	biginteger: "bigInt",
+	smallint: "smallInt",
+	tinyint: "tinyInt",
+	float: "float",
+	double: "double",
+	bool: "bool",
+	boolean: "bool",
+	string: "varchar",
+	varchar: "varchar",
+	nchar: "nchar",
+	binary: "varbinary",
+	varbinary: "varbinary",
+	json: "json",
+	decimal: "decimal",
+	// `satisfies` makes this exhaustive + exact against EonLogicalType (a missing
+	// or stray key is a compile error) while the exported map stays string-keyed
+	// so an arbitrary logical string can be looked up without a cast.
+} satisfies Record<EonLogicalType, string>;
+
+export const TYPE_KIND_MAP: Record<string, string> = TYPE_KIND_ENTRIES;
+
+/** A column or tag definition — the flattened `StableColumnDef` + `ColumnTypeSpec`. */
+export interface EonColumnSpec {
+	name: string;
+	kind: string;
+	length: number | null;
+	precision: number | null;
+	scale: number | null;
+}
+
+export interface CreateStableSpec {
+	kind: "createStable";
+	name: string;
+	columns: EonColumnSpec[];
+	tags: EonColumnSpec[];
+	ifNotExists: boolean;
+	/** Optional STABLE `KEEP` retention (a 3.3.x+ TDengine feature). Validated as a duration in Rust. */
+	keep?: string;
+}
+
+/** One `ALTER STABLE` change — tagged on `op`, mirroring the Rust `AlterChange`. */
+export type AlterChange =
+	| { op: "addColumn"; name: string; type: Omit<EonColumnSpec, "name"> }
+	| { op: "dropColumn"; name: string }
+	| { op: "modifyColumn"; name: string; type: Omit<EonColumnSpec, "name"> }
+	| { op: "addTag"; name: string; type: Omit<EonColumnSpec, "name"> }
+	| { op: "dropTag"; name: string }
+	| { op: "modifyTag"; name: string; type: Omit<EonColumnSpec, "name"> }
+	| { op: "renameTag"; from: string; to: string };
+
+export interface AlterStableSpec {
+	kind: "alterStable";
+	name: string;
+	changes: AlterChange[];
+}
+
+export interface CreateChildTableSpec {
+	kind: "createChildTable";
+	name: string;
+	using: string;
+	tags: unknown[];
+	ifNotExists: boolean;
+	/** Inline tag values as SQL literals (58.3 `exec`) vs `?` placeholders (STMT, 58.4). */
+	literal: boolean;
+	/** Optional child-table `TTL` in whole days (`>= 0`, a 3.3.x+ TDengine feature). */
+	ttl?: number;
+}
+
+export interface DropStableSpec {
+	kind: "dropStable";
+	name: string;
+	ifExists: boolean;
+}
+
+/** TDengine timestamp precision — the create-only `PRECISION` database option. */
+export type EonPrecision = "ms" | "us" | "ns";
+
+/** TDengine `CACHEMODEL` allowlist. */
+export type EonCacheModel = "none" | "last_row" | "last_value" | "both";
+
+/**
+ * `CREATE DATABASE` options (retention / storage). Every value is validated in
+ * Rust (durations, precision/cachemodel/wal-level allowlists, `KEEP >= 3x
+ * DURATION`). Options are emitted only when present, in a fixed order.
+ */
+export interface EonDatabaseOptions {
+	/** Retention duration (e.g. `"90d"`). Must be `>= 3 x DURATION` when both are set with the same unit. */
+	keep?: string;
+	/** Per-file time span (e.g. `"10d"`). Create-only — cannot be altered. */
+	duration?: string;
+	/** Timestamp precision. Create-only — cannot be altered. */
+	precision?: EonPrecision;
+	/** Write buffer size in MB. */
+	buffer?: number;
+	/** WAL level (1 or 2). */
+	walLevel?: 1 | 2;
+	/** Row cache mode. */
+	cachemodel?: EonCacheModel;
+}
+
+export interface CreateDatabaseSpec extends EonDatabaseOptions {
+	kind: "createDatabase";
+	name: string;
+	ifNotExists: boolean;
+}
+
+/**
+ * `ALTER DATABASE` — TDengine changes exactly ONE option per statement, so
+ * exactly one field must be set. Create-only options (`PRECISION`/`DURATION`)
+ * are intentionally absent here.
+ */
+export interface EonAlterDatabaseOptions {
+	keep?: string;
+	buffer?: number;
+	walLevel?: 1 | 2;
+	cachemodel?: EonCacheModel;
+	replica?: number;
+	minrows?: number;
+}
+
+export interface AlterDatabaseSpec {
+	kind: "alterDatabase";
+	name: string;
+	/** The Rust-side option name (e.g. `"keep"`, `"wal_level"`). */
+	option: string;
+	value: string | number;
+}
+
+/** A basic (non-super) table: first column `TIMESTAMP`, then columns, no `TAGS`. */
+export interface CreateTableSpec {
+	kind: "createTable";
+	name: string;
+	columns: EonColumnSpec[];
+	ifNotExists: boolean;
+}
+
+export interface DropTableSpec {
+	kind: "dropTable";
+	name: string;
+	ifExists: boolean;
+}