@c9up/eon 0.1.0

package/src/index.ts

@@ -0,0 +1,118 @@
+import "reflect-metadata";
+
+export {
+	defineConfig,
+	type EonConfig,
+	type EonConnectionConfig,
+} from "./connection/config.js";
+export {
+	type EonBindKind,
+	type EonBoundColumn,
+	type EonChildBatch,
+	type EonColumnarIngest,
+	type EonConnection,
+	EonConnectionError,
+	type EonLineProtocol,
+	type EonSchemalessOptions,
+	type EonSchemalessPrecision,
+} from "./connection/EonConnection.js";
+export { connectWsEon } from "./connection/websocket.js";
+export {
+	Column,
+	type EonColumnMetadata,
+	type EonColumnOptions,
+	type EonTagMetadata,
+	type EonTagOptions,
+	getColumnMetadata,
+	getSuperTableMetadata,
+	getTagMetadata,
+	getTimestampColumn,
+	SuperTable,
+	type SuperTableMetadata,
+	Tag,
+	Timestamp,
+} from "./decorators/superTable.js";
+export type {
+	EonAppContext,
+	EonConnector,
+	EonService,
+} from "./EonProvider.js";
+export { EonProvider } from "./EonProvider.js";
+export { toLineProtocol } from "./ingest/schemaless.js";
+export { buildLiteralInserts } from "./ingest/sql.js";
+export {
+	buildColumnarIngest,
+	type ColumnarPlan,
+	compileStmtTemplate,
+	DEFAULT_BATCH_SIZE,
+	groupByChild,
+	type IngestPoint,
+	type PlanColumn,
+	toBindKind,
+} from "./ingest/stmt.js";
+export {
+	type CompiledStatement,
+	compileStatementNative,
+	type EonDialect,
+	quoteIdentNative,
+} from "./query/native.js";
+export {
+	type EonFillMode,
+	type EonFunctionSelect,
+	type EonOrderDirection,
+	type EonPseudoSelect,
+	type EonScalar,
+	type EonSelectItem,
+	type EonWhereOperator,
+	type EonWhereValue,
+	TimeSeriesQuery,
+} from "./query/TimeSeriesQuery.js";
+export {
+	SuperTableRepository,
+	type SuperTableRepositoryOptions,
+} from "./repository/SuperTableRepository.js";
+export {
+	type AlterChange,
+	type AlterDatabaseSpec,
+	type AlterStableSpec,
+	type CreateChildTableSpec,
+	type CreateDatabaseSpec,
+	type CreateStableSpec,
+	type CreateTableSpec,
+	type DropStableSpec,
+	type DropTableSpec,
+	type EonAlterDatabaseOptions,
+	type EonCacheModel,
+	type EonColumnSpec,
+	type EonDatabaseOptions,
+	type EonLogicalType,
+	type EonPrecision,
+	TYPE_KIND_MAP,
+} from "./schema/CreateStableSpec.js";
+export {
+	compileCreateStableSpec,
+	requireSuperTableName,
+	type SuperTableClass,
+} from "./schema/compile.js";
+export {
+	type EonMigrationOptions,
+	EonMigrationRunner,
+	type MigrationState,
+	type MigrationStatus,
+} from "./schema/EonMigrationRunner.js";
+export {
+	AlterStableBuilder,
+	type AlterTypeSetter,
+	BasicTableBuilder,
+	EonSchema,
+	StableBuilder,
+	type StableColumnHandle,
+} from "./schema/EonSchema.js";
+export { Migration } from "./schema/Migration.js";
+export {
+	type CreateChildTableOptions,
+	childTableName,
+	createChildTable,
+	dropSuperTable,
+	syncSuperTable,
+} from "./schema/sync.js";

package/src/ingest/schemaless.ts

@@ -0,0 +1,211 @@
+/**
+ * Schemaless line-protocol rendering (story 58.4, AC4).
+ *
+ * Renders points to InfluxDB line-protocol strings for
+ * `EonConnection.schemaless`. This is NOT SQL — it is InfluxDB's line format, so
+ * it is rendered in TS (no compiler seam), with the format's own escaping rules
+ * applied to the measurement, tag keys/values, and field keys, and string field
+ * values double-quoted (context7 `/taosdata/tdengine`, InfluxDB line protocol).
+ *
+ * Schemaless is a documented ~8–10× slower helper than the STMT path and must
+ * NOT be used as the default bulk path (AD5 / AC4).
+ */
+
+import type { EonBindKind } from "../connection/EonConnection.js";
+import type { ColumnarPlan, IngestPoint } from "./stmt.js";
+import { coerceTimestamp, FLOAT32_MAX, INT_BOUNDS } from "./stmt.js";
+
+/**
+ * Reject any control character (newline, CR, tab, NUL, …). Line protocol is
+ * newline-delimited and cannot encode a control byte in ANY position, so
+ * backslash-escaping does not neutralize it — a raw newline in a caller tag or
+ * field value would terminate the line and inject a forged point. These bytes
+ * must be refused, not escaped (memory `feedback_security_first`).
+ */
+function assertNoControlChar(value: string, role: string): void {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code <= 0x1f || code === 0x7f) {
+			throw new Error(
+				`[E_EON_SCHEMALESS_CONTROL_CHAR] ${role} contains a control character (code ${code}); line protocol cannot encode it.`,
+			);
+		}
+	}
+}
+
+/**
+ * Escape a measurement name: comma, space, and backslash. Backslash is escaped
+ * too, else a trailing `\` would escape the following delimiter and desync the
+ * parser. Control chars are rejected upstream (so no `\s`).
+ */
+function escapeMeasurement(value: string): string {
+	assertNoControlChar(value, "measurement");
+	return value.replace(/[\\, ]/g, "\\$&");
+}
+
+/** Escape a tag key/value or field key: comma, equals, space, and backslash. */
+function escapeKeyOrTag(value: string): string {
+	assertNoControlChar(value, "tag/field key or value");
+	return value.replace(/[\\,= ]/g, "\\$&");
+}
+
+/** Escape a string field value: backslash and double-quote (then wrap in `"`). */
+function quoteStringField(value: string): string {
+	assertNoControlChar(value, "string field value");
+	return `"${value.replace(/["\\]/g, "\\$&")}"`;
+}
+
+/**
+ * Render one field value into its line-protocol form, typed by its bind kind.
+ * Numeric kinds are validated to the same precision/finiteness contract the STMT
+ * path enforces (`E_EON_PARAM_PRECISION`): an unsafe-integer `number`, a
+ * non-finite float, or a non-numeric value is rejected loud rather than emitted
+ * as a lossy/invalid token (e.g. `1e+21i`, `NaNi`) that silently corrupts data.
+ */
+function renderFieldValue(
+	kind: EonBindKind,
+	value: unknown,
+	property: string,
+): string {
+	switch (kind) {
+		case "int":
+		case "bigInt":
+		case "smallInt":
+		case "tinyInt": {
+			// Integer field: the `i` suffix. bigint is exact; a `number` must be a
+			// safe integer or it has already lost precision. The value must also fit
+			// the column width — the SQL path's i64 guard (`stringifyPrecisionSafe`)
+			// never runs on the schemaless path, so bound it here or an out-of-range
+			// value renders as an invalid/overflowing token (`999...i`).
+			let asBig: bigint;
+			if (typeof value === "bigint") {
+				asBig = value;
+			} else if (
+				typeof value === "number" &&
+				Number.isInteger(value) &&
+				Number.isSafeInteger(value)
+			) {
+				asBig = BigInt(value);
+			} else {
+				throw new Error(
+					`[E_EON_PARAM_PRECISION] integer field '${property}' value ${String(value)} is not a safe integer; pass i64 values as bigint.`,
+				);
+			}
+			const [min, max] = INT_BOUNDS[kind];
+			if (asBig < min || asBig > max) {
+				throw new Error(
+					`[E_EON_SCHEMALESS_FIELD] ${kind} field '${property}' value ${String(value)} is outside the ${kind} range [${min}, ${max}].`,
+				);
+			}
+			return `${asBig}i`;
+		}
+		case "float":
+		case "double":
+		case "decimal": {
+			const asNum =
+				typeof value === "bigint"
+					? Number(value)
+					: typeof value === "number"
+						? value
+						: undefined;
+			if (asNum === undefined || !Number.isFinite(asNum)) {
+				throw new Error(
+					`[E_EON_SCHEMALESS_FIELD] numeric field '${property}' value ${String(value)} is not a finite number.`,
+				);
+			}
+			if (kind === "float" && Math.abs(asNum) > FLOAT32_MAX) {
+				throw new Error(
+					`[E_EON_SCHEMALESS_FIELD] float (f32) field '${property}' value ${String(value)} exceeds the binary32 range and would render as Infinity.`,
+				);
+			}
+			return `${value}`;
+		}
+		case "bool":
+			if (typeof value !== "boolean") {
+				throw new Error(
+					`[E_EON_SCHEMALESS_FIELD] bool field '${property}' requires a boolean (got ${typeof value}).`,
+				);
+			}
+			return value ? "true" : "false";
+		default:
+			// varchar / nchar / varbinary / json / timestamp → quoted string.
+			// A non-scalar (object/array) would stringify to "[object Object]" /
+			// "a,b" — silent corruption. Reject loud rather than emit garbage.
+			if (typeof value === "object") {
+				throw new Error(
+					`[E_EON_SCHEMALESS_FIELD] string field '${property}' requires a scalar value, not an object/array.`,
+				);
+			}
+			return quoteStringField(String(value));
+	}
+}
+
+/**
+ * Render points to InfluxDB line-protocol lines. The measurement is the
+ * super-table name, tags come from the entity's `@Tag` columns, and every
+ * present metric column (excluding the timestamp) becomes a field. Points with
+ * no fields are skipped (line protocol requires ≥1 field) — reported by the
+ * caller, never silently emitted as an invalid line.
+ */
+export function toLineProtocol(
+	plan: ColumnarPlan,
+	points: readonly IngestPoint[],
+): string[] {
+	if (plan.stable === "") {
+		throw new Error(
+			"[E_EON_SCHEMALESS_MEASUREMENT] super-table (measurement) name is empty; cannot render a line-protocol point.",
+		);
+	}
+	const measurement = escapeMeasurement(plan.stable);
+	const lines: string[] = [];
+
+	for (const point of points) {
+		const tagParts = plan.tags
+			.filter((tag) => point[tag.property] != null)
+			.map((tag) => {
+				const value = point[tag.property];
+				// Tags are not type-checked like fields; a non-scalar (object/array)
+				// would stringify to "[object Object]" / "a,b" — silent corruption.
+				if (typeof value === "object") {
+					throw new Error(
+						`[E_EON_SCHEMALESS_TAG] tag '${tag.property}' requires a scalar value, not an object/array.`,
+					);
+				}
+				const raw = String(value);
+				// Line protocol forbids an empty tag value (`location=` is invalid and
+				// TDengine rejects the whole batch). Reject loud rather than emit a
+				// malformed token — a control char in `raw` is caught by escapeKeyOrTag.
+				if (raw === "") {
+					throw new Error(
+						`[E_EON_SCHEMALESS_EMPTY_TAG] tag '${tag.property}' is an empty string; line protocol requires a non-empty tag value.`,
+					);
+				}
+				return `${escapeKeyOrTag(tag.property)}=${escapeKeyOrTag(raw)}`;
+			});
+
+		const fieldParts = plan.columns
+			.filter(
+				(col) =>
+					col.property !== plan.tsProperty && point[col.property] != null,
+			)
+			.map(
+				(col) =>
+					`${escapeKeyOrTag(col.property)}=${renderFieldValue(col.kind, point[col.property], col.property)}`,
+			);
+
+		if (fieldParts.length === 0) {
+			throw new Error(
+				`[E_EON_SCHEMALESS_NO_FIELDS] point for '${plan.stable}' has no metric fields; line protocol requires at least one field.`,
+			);
+		}
+
+		const ts = coerceTimestamp(point[plan.tsProperty], plan.tsProperty);
+		const prefix =
+			tagParts.length > 0
+				? `${measurement},${tagParts.join(",")}`
+				: measurement;
+		lines.push(`${prefix} ${fieldParts.join(",")} ${ts}`);
+	}
+
+	return lines;
+}

package/src/ingest/sql.ts

@@ -0,0 +1,73 @@
+/**
+ * Literal SQL INSERT ingest planning (story 58.4, AC5) — the convenience /
+ * fallback path that runs through the literal-only `EonConnection.exec`.
+ *
+ * Because `exec` takes literal SQL (no bind params, 58.2 D3), the value literals
+ * are rendered by the **Rust compiler's `literal: true` INSERT mode** (D6, OQ1),
+ * reusing the single `render_literal` injection seam. This module NEVER
+ * string-builds SQL or interpolates a value — it assembles a JSON `InsertSpec`
+ * and hands it to `compileStatementNative`. It groups points by child table
+ * (the `USING … TAGS` auto-create form) exactly like the STMT path.
+ */
+
+import { compileStatementNative } from "../query/native.js";
+import type { ColumnarPlan, IngestPoint } from "./stmt.js";
+import { assertColumnValue, coerceTimestamp, groupByChild } from "./stmt.js";
+
+/**
+ * Build one literal `INSERT … USING <stable> TAGS(...) VALUES(...)` statement per
+ * child table. Every value is validated against its declared bind kind up front —
+ * the timestamp through `coerceTimestamp` (rejecting fractional/string/unsafe
+ * inputs the compile boundary alone would pass, e.g. `1700000000000.5` or a date
+ * string), other columns through `assertColumnValue` — so the literal path is
+ * exactly as precision- and type-safe as the STMT path, and the Rust compiler
+ * renders only the vetted literals (never TS interpolation).
+ */
+export function buildLiteralInserts(
+	plan: ColumnarPlan,
+	points: readonly IngestPoint[],
+): string[] {
+	const columnNames = plan.columns.map((c) => c.property);
+	const tagProps = plan.tags.map((t) => t.property);
+	const statements: string[] = [];
+
+	for (const group of groupByChild(plan.stable, tagProps, points)) {
+		const rows = group.rows.map((point) =>
+			plan.columns.map((col) => {
+				if (col.property === plan.tsProperty) {
+					return coerceTimestamp(point[col.property], col.property);
+				}
+				const value = point[col.property] ?? null;
+				assertColumnValue(value, col.kind, col.property);
+				return value;
+			}),
+		);
+		const compiled = compileStatementNative(
+			{
+				kind: "insert",
+				table: group.table,
+				using: plan.stable,
+				tags: group.tagValues.map((v, i) => {
+					const value = v ?? null;
+					const tag = plan.tags[i];
+					if (tag !== undefined)
+						assertColumnValue(value, tag.kind, tag.property);
+					return value;
+				}),
+				columns: columnNames,
+				rows,
+				literal: true,
+			},
+			"tdengine",
+		);
+		const [sql, ...rest] = compiled.statements;
+		if (sql === undefined || rest.length > 0) {
+			throw new Error(
+				`[E_EON_LITERAL_INSERT] expected exactly one statement for child '${group.table}', got ${compiled.statements.length}`,
+			);
+		}
+		statements.push(sql);
+	}
+
+	return statements;
+}