@c9up/eon 0.1.0

package/dist/schema/EonMigrationRunner.js

@@ -0,0 +1,295 @@
+/**
+ * `EonMigrationRunner` — discovers, executes, and tracks eon (TDengine)
+ * migrations. Mirrors atlas `MigrationRunner` (`schema/MigrationRunner.ts`):
+ * sorted-file discovery, a `ream_`-prefixed tracking table, batch-based
+ * rollback, `init/status/migrate/rollback/reset/refresh/fresh/dryRun`.
+ *
+ * ── TWO named TDengine deviations from atlas (AC6) ──────────────────────────
+ *
+ *  1. **No transactions / no engine rollback.** TDengine DDL is non-transactional
+ *     — a batch CANNOT be applied atomically. The runner executes statements
+ *     **sequentially**; a mid-migration failure leaves earlier statements
+ *     applied. The mitigation is idempotent DDL (`IF (NOT) EXISTS`, the
+ *     `EonSchema` default) so a re-run converges. There is NO `runInTransaction`.
+ *
+ *  2. **No `UNIQUE`, no auto-increment.** The tracking table is a basic table
+ *     `ream_eon_migrations(executed_at TIMESTAMP, name VARCHAR(255), batch INT)`;
+ *     the applied-set is de-duped **by name in JS**, and each record is written
+ *     with a strictly-increasing `executed_at` so rollback can delete it by that
+ *     unique timestamp key (TDengine only allows a `DELETE` predicate on the
+ *     primary timestamp column).
+ *
+ * Agnostic leaf: takes the connection structurally and a plain directory path —
+ * no `@c9up/ream` import, no app helper (`project_package_extraction`).
+ */
+import * as fsp from "node:fs/promises";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { compileStatementNative } from "../query/native.js";
+const DEFAULT_DIR = "database/eon-migrations";
+const DEFAULT_TABLE = "ream_eon_migrations";
+const TABLE_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Migration filename (no extension): no path separators, no `..`. */
+const MIGRATION_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+export class EonMigrationRunner {
+    #conn;
+    #dir;
+    #table;
+    constructor(conn, options = {}) {
+        this.#conn = conn;
+        this.#dir = options.migrationsDir ?? DEFAULT_DIR;
+        const table = options.tableName ?? DEFAULT_TABLE;
+        if (!TABLE_NAME_PATTERN.test(table)) {
+            throw new Error(`[E_EON_MIGRATION_INVALID] invalid tracking-table name '${table}'; must match ${TABLE_NAME_PATTERN}`);
+        }
+        this.#table = table;
+    }
+    /** Create the tracking table (`IF NOT EXISTS`) via the basic-table DDL path. */
+    async init() {
+        const { statements } = compileStatementNative({
+            kind: "createTable",
+            name: this.#table,
+            ifNotExists: true,
+            columns: [
+                {
+                    name: "executed_at",
+                    kind: "timestamp",
+                    length: null,
+                    precision: null,
+                    scale: null,
+                },
+                {
+                    name: "name",
+                    kind: "varchar",
+                    length: 255,
+                    precision: null,
+                    scale: null,
+                },
+                {
+                    name: "batch",
+                    kind: "int",
+                    length: null,
+                    precision: null,
+                    scale: null,
+                },
+            ],
+        }, "tdengine");
+        for (const sql of statements)
+            await this.#conn.exec(sql);
+    }
+    /** The status of every discovered migration (applied vs pending). */
+    async status() {
+        await this.init();
+        const applied = await this.#appliedRecords();
+        const byName = new Map(applied.map((r) => [r.name, r.batch]));
+        const files = await this.#discoverFiles();
+        return files.map((name) => {
+            const batch = byName.get(name);
+            return batch === undefined
+                ? { name, state: "pending" }
+                : { name, state: "applied", batch };
+        });
+    }
+    /** Run every pending migration (filename order), recording each. */
+    async migrate() {
+        await this.init();
+        const applied = await this.#appliedRecords();
+        const appliedNames = new Set(applied.map((r) => r.name));
+        const files = await this.#discoverFiles();
+        const pending = files.filter((f) => !appliedNames.has(f));
+        if (pending.length === 0)
+            return [];
+        const batch = this.#maxBatch(applied) + 1;
+        // Strictly-increasing executed_at (unique key for rollback deletes) — never
+        // below any existing record, never colliding within this run.
+        let clock = Math.max(Date.now(), this.#maxExecutedAt(applied) + 1);
+        const executed = [];
+        for (const name of pending) {
+            const migration = await this.#loadMigration(name);
+            for (const sql of await migration.getUpSQL()) {
+                await this.#conn.exec(sql);
+            }
+            await this.#writeRecord(name, batch, clock);
+            clock += 1;
+            executed.push(name);
+        }
+        return executed;
+    }
+    /** Roll back the most-recent batch (files in reverse order), running `down()`. */
+    async rollback() {
+        await this.init();
+        const applied = await this.#appliedRecords();
+        if (applied.length === 0)
+            return [];
+        const batch = this.#maxBatch(applied);
+        const inBatch = new Map(applied.filter((r) => r.batch === batch).map((r) => [r.name, r]));
+        const files = await this.#discoverFiles();
+        // Reverse of application order = reverse of filename order within the batch.
+        const ordered = files.filter((f) => inBatch.has(f)).reverse();
+        const rolled = [];
+        for (const name of ordered) {
+            const record = inBatch.get(name);
+            if (record === undefined)
+                continue;
+            const migration = await this.#loadMigration(name);
+            for (const sql of await migration.getDownSQL()) {
+                await this.#conn.exec(sql);
+            }
+            await this.#deleteRecord(record.executed_at);
+            rolled.push(name);
+        }
+        return rolled;
+    }
+    /** Roll back every applied batch (Lucid `migrate:reset`). */
+    async reset() {
+        await this.init();
+        const all = [];
+        // Guard against a stuck loop: each rollback must shrink the applied set.
+        for (;;) {
+            const rolled = await this.rollback();
+            if (rolled.length === 0)
+                break;
+            all.push(...rolled);
+        }
+        return all;
+    }
+    /** Reset then re-run every migration (Lucid `migrate:refresh`). */
+    async refresh() {
+        const rolled = await this.reset();
+        const executed = await this.migrate();
+        return { rolled, executed };
+    }
+    /** Alias of {@link refresh} (Lucid `migrate:fresh`). */
+    fresh() {
+        return this.refresh();
+    }
+    /** Compute the SQL each pending migration would emit, WITHOUT executing it. */
+    async dryRun() {
+        await this.init();
+        const applied = await this.#appliedRecords();
+        const appliedNames = new Set(applied.map((r) => r.name));
+        const pending = (await this.#discoverFiles()).filter((f) => !appliedNames.has(f));
+        const result = [];
+        for (const name of pending) {
+            const migration = await this.#loadMigration(name);
+            result.push({ name, sql: await migration.getUpSQL() });
+        }
+        return result;
+    }
+    /** Read every tracking record (name, batch, executed_at). */
+    async #appliedRecords() {
+        const { statements } = compileStatementNative({
+            kind: "select",
+            table: this.#table,
+            select: ["name", "batch", "executed_at"],
+        }, "tdengine");
+        const sql = statements[0];
+        if (sql === undefined)
+            return [];
+        const rows = await this.#conn.query(sql);
+        return rows.map((r) => ({
+            name: String(r.name),
+            batch: Number(r.batch),
+            executed_at: Number(r.executed_at),
+        }));
+    }
+    #maxBatch(records) {
+        return records.reduce((max, r) => Math.max(max, r.batch), 0);
+    }
+    #maxExecutedAt(records) {
+        return records.reduce((max, r) => Math.max(max, r.executed_at), 0);
+    }
+    /** Insert a tracking record via the literal INSERT compiler (never TS interpolation). */
+    async #writeRecord(name, batch, executedAt) {
+        const { statements } = compileStatementNative({
+            kind: "insert",
+            table: this.#table,
+            columns: ["executed_at", "name", "batch"],
+            rows: [[executedAt, name, batch]],
+            literal: true,
+        }, "tdengine");
+        for (const sql of statements)
+            await this.#conn.exec(sql);
+    }
+    /** Delete a tracking record by its unique `executed_at` key (compiled in Rust). */
+    async #deleteRecord(executedAt) {
+        const { statements } = compileStatementNative({
+            kind: "delete",
+            table: this.#table,
+            column: "executed_at",
+            value: executedAt,
+        }, "tdengine");
+        for (const sql of statements)
+            await this.#conn.exec(sql);
+    }
+    /** Discover migration files (`.ts`/`.js`), sorted, extension stripped. */
+    async #discoverFiles() {
+        try {
+            const entries = await fsp.readdir(this.#dir);
+            return entries
+                .filter((f) => f.endsWith(".ts") || f.endsWith(".js"))
+                .sort()
+                .map((f) => f.replace(/\.(ts|js)$/, ""));
+        }
+        catch (err) {
+            // A missing migrations directory → no migrations. Anything else propagates.
+            if (typeof err === "object" &&
+                err !== null &&
+                Reflect.get(err, "code") === "ENOENT") {
+                return [];
+            }
+            throw err;
+        }
+    }
+    /** Load + instantiate a migration's default-export class. */
+    async #loadMigration(name) {
+        if (!MIGRATION_NAME_PATTERN.test(name) || name.includes("..")) {
+            throw new Error(`[E_EON_MIGRATION_INVALID] unsafe migration name '${name}'`);
+        }
+        const tsPath = path.join(this.#dir, `${name}.ts`);
+        const jsPath = path.join(this.#dir, `${name}.js`);
+        const tsExists = await pathExists(tsPath);
+        // Fail loud with the runner's own error (atlas parity) instead of letting
+        // `import` throw a raw ERR_MODULE_NOT_FOUND on a missing/renamed file.
+        if (!tsExists && !(await pathExists(jsPath))) {
+            throw new Error(`[E_EON_MIGRATION_INVALID] migration '${name}' not found (no .ts or .js file in ${this.#dir})`);
+        }
+        const filePath = tsExists ? tsPath : jsPath;
+        // ESM dynamic import needs a file:// URL (Windows rejects a bare path).
+        const mod = await import(pathToFileURL(path.resolve(filePath)).href);
+        const MigrationClass = mod.default;
+        if (!isConstructor(MigrationClass)) {
+            throw new Error(`[E_EON_MIGRATION_INVALID] migration '${name}' must export a default class`);
+        }
+        const instance = new MigrationClass();
+        if (!isMigration(instance)) {
+            throw new Error(`[E_EON_MIGRATION_INVALID] migration '${name}' default export is not a Migration (missing up/down)`);
+        }
+        return instance;
+    }
+}
+function isConstructor(value) {
+    return typeof value === "function";
+}
+/**
+ * Structural Migration guard — avoids importing the class value for an
+ * `instanceof`. Reads through the prototype chain (methods live on the
+ * prototype, not as own enumerable props) via `Reflect.get`.
+ */
+function isMigration(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const up = Reflect.get(value, "getUpSQL");
+    const down = Reflect.get(value, "getDownSQL");
+    return typeof up === "function" && typeof down === "function";
+}
+async function pathExists(p) {
+    try {
+        await fsp.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=EonMigrationRunner.js.map

package/dist/schema/EonMigrationRunner.js.map

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

package/dist/schema/EonSchema.d.ts

@@ -0,0 +1,128 @@
+/**
+ * `EonSchema` — the fluent DDL surface a migration's `up()`/`down()` drives.
+ *
+ * Mirrors atlas `Schema` (`schema/Schema.ts`) in shape: each method compiles its
+ * spec through the Rust `compileStatementNative` seam and appends the resulting
+ * SQL to an internal buffer the runner flushes. The TS side NEVER string-builds
+ * SQL — every identifier, literal, and option value is quoted/validated in Rust
+ * (the injection seam stays in one place, memory `feedback_security_first`).
+ *
+ * The `StableBuilder` is intentionally THINNER than atlas `TableBuilder`:
+ * TDengine columns have no `DEFAULT`, no per-column `PRIMARY KEY` choice (the
+ * first `TIMESTAMP` is always the key), no `UNIQUE`, no foreign keys, no SQL
+ * secondary indexes — so `defaultTo`/`primary`/`unique`/`references`/`increments`
+ * have NO analogue and are deliberately absent (D — the reconciliation note).
+ */
+import type { AlterChange, EonAlterDatabaseOptions, EonColumnSpec, EonDatabaseOptions } from "./CreateStableSpec.js";
+/** The type portion of an `EonColumnSpec` (everything but the name). */
+type EonType = Omit<EonColumnSpec, "name">;
+/**
+ * The thin column/tag surface shared by every builder: only column-type methods
+ * (+ length/precision/scale). No `defaultTo`/`primary`/`unique` — TDengine has
+ * no analogue. Each method appends a column via `#add` and returns whatever that
+ * hook returns (a tag-handle for stables, `void` for basic tables).
+ */
+declare abstract class ColumnMethods<R> {
+    protected abstract add(spec: EonColumnSpec): R;
+    timestamp(name: string): R;
+    int(name: string): R;
+    bigInteger(name: string): R;
+    float(name: string): R;
+    double(name: string): R;
+    bool(name: string): R;
+    varchar(name: string, length: number): R;
+    nchar(name: string, length: number): R;
+    binary(name: string, length: number): R;
+    decimal(name: string, precision: number, scale?: number): R;
+    json(name: string): R;
+}
+/**
+ * The no-name type surface for an `ALTER STABLE` add/modify change: the column
+ * name is already fixed (by `addColumn(name)` etc.), so these methods take ONLY
+ * the type arguments and finalize the change.
+ */
+declare abstract class TypeMethods<R> {
+    protected abstract emit(type: EonType): R;
+    timestamp(): R;
+    int(): R;
+    bigInteger(): R;
+    float(): R;
+    double(): R;
+    bool(): R;
+    varchar(length: number): R;
+    nchar(length: number): R;
+    binary(length: number): R;
+    decimal(precision: number, scale?: number): R;
+    json(): R;
+}
+/** A handle returned by a `StableBuilder` column method — `.tag()` re-homes it as a tag. */
+export interface StableColumnHandle {
+    /** Mark the just-declared column as a `TAG` instead of a metric column. */
+    tag(): void;
+}
+/** Fluent builder for `CREATE STABLE` columns + tags (ts-first is enforced in Rust). */
+export declare class StableBuilder extends ColumnMethods<StableColumnHandle> {
+    #private;
+    protected add(spec: EonColumnSpec): StableColumnHandle;
+    /** @internal */
+    columns(): EonColumnSpec[];
+    /** @internal */
+    tags(): EonColumnSpec[];
+}
+/** Fluent builder for a basic (non-super) table — same columns, no tags. */
+export declare class BasicTableBuilder extends ColumnMethods<void> {
+    #private;
+    protected add(spec: EonColumnSpec): void;
+    /** @internal */
+    columns(): EonColumnSpec[];
+}
+/** Sets the type on a pending `ALTER STABLE` add/modify change, then records it. */
+export interface AlterTypeSetter extends TypeMethods<void> {
+}
+/** Fluent builder for `ALTER STABLE` — one method per TDengine change op. */
+export declare class AlterStableBuilder {
+    #private;
+    addColumn(name: string): AlterTypeSetter;
+    modifyColumn(name: string): AlterTypeSetter;
+    dropColumn(name: string): this;
+    addTag(name: string): AlterTypeSetter;
+    modifyTag(name: string): AlterTypeSetter;
+    dropTag(name: string): this;
+    renameTag(from: string, to: string): this;
+    /** @internal */
+    changes(): AlterChange[];
+}
+export declare class EonSchema {
+    #private;
+    /**
+     * `CREATE STABLE`. Defaults to `IF NOT EXISTS` (idempotent DDL — the mitigation
+     * for TDengine's non-transactional migrations, AC6). Pass `keep` for retention.
+     */
+    createStable(name: string, callback: (table: StableBuilder) => void, options?: {
+        ifNotExists?: boolean;
+        keep?: string;
+    }): this;
+    /** `ALTER STABLE` → one statement per change. */
+    alterStable(name: string, callback: (table: AlterStableBuilder) => void): this;
+    /** `DROP STABLE IF EXISTS`. */
+    dropStable(name: string): this;
+    /** `CREATE DATABASE IF NOT EXISTS` with optional retention/storage options. */
+    createDatabase(name: string, options?: EonDatabaseOptions): this;
+    /**
+     * `ALTER DATABASE` — exactly ONE option per call (TDengine restriction).
+     * Throws if zero or more than one option key is provided.
+     */
+    alterDatabase(name: string, options: EonAlterDatabaseOptions): this;
+    /** `CREATE TABLE IF NOT EXISTS` — a basic (non-super) table, no tags. */
+    createTable(name: string, callback: (table: BasicTableBuilder) => void): this;
+    /** `DROP TABLE IF EXISTS`. */
+    dropTable(name: string): this;
+    /** Queue a raw SQL statement verbatim (an escape hatch for options not modelled above). */
+    raw(sql: string): this;
+    /** Clear the buffer (called before each `up()`/`down()` run). */
+    reset(): void;
+    /** The compiled SQL statements queued so far. */
+    toSQL(): string[];
+}
+export {};
+//# sourceMappingURL=EonSchema.d.ts.map

package/dist/schema/EonSchema.d.ts.map

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