ts-prorm-orm 1.1.0

package/dist/dialects/singlestore/index.js

@@ -0,0 +1,354 @@
+"use strict";
+/**
+ * SingleStore (formerly MemSQL) dialect implementation for the TypeScript ORM.
+ *
+ * SingleStore is MySQL-wire-compatible, so this dialect extends
+ * {@link MySQLDialect} and reuses the exact same `mysql2` driver, connection
+ * pooling, query execution, escaping, WHERE/ORDER/INSERT/UPDATE/DELETE/SELECT
+ * builders, JSON helpers, etc. Only the grammar that genuinely differs from
+ * stock MySQL is overridden here.
+ *
+ * Notable differences from the MySQL dialect:
+ *
+ * - `name` is `'singlestore'` (the driver/`library` is still `'mysql2'`).
+ * - Default SQL port is 3306 (same wire protocol as MySQL).
+ * - Table storage kind: SingleStore tables are columnstore by default. A
+ *   `ROWSTORE` table can be requested with `{ rowstore: true }`, which emits
+ *   `CREATE ROWSTORE TABLE ...`.
+ * - `SHARD KEY (cols)`: SingleStore is a distributed database and shards data
+ *   across leaf nodes by a shard key. `{ shardKey: ['id'] }` emits
+ *   `SHARD KEY (id)`. An empty array (`{ shardKey: [] }`) emits a keyless
+ *   `SHARD KEY ()` (random sharding), which is also how a plain distributed
+ *   table with no explicit shard key is declared.
+ * - `SORT KEY (cols)`: columnstore tables store rows ordered by a sort key.
+ *   `{ sortKey: ['created_at'] }` emits `SORT KEY (created_at)`.
+ * - `KEY (...) USING CLUSTERED COLUMNSTORE`: the explicit clustered-columnstore
+ *   key form, requested with `{ columnstoreKey: { fields: [...] } }`.
+ * - Reference tables: `{ reference: true }` emits `CREATE REFERENCE TABLE ...`.
+ *   Reference tables are fully replicated to every node (rather than sharded),
+ *   and are typically used for small dimension tables joined against large
+ *   sharded fact tables.
+ *
+ * CAVEAT — foreign keys: SingleStore does NOT support foreign key constraints
+ * (a real server rejects `FOREIGN KEY ... REFERENCES ...`). This dialect
+ * therefore refuses to emit FK SQL rather than generating statements that
+ * would fail:
+ *   - CREATE TABLE: table-level FOREIGN KEY constraints and column-level
+ *     `references` are omitted (the table is still created, minus the FK).
+ *   - {@link addForeignKey} and {@link createConstraint} with a FOREIGN KEY
+ *     type throw a clear error.
+ *   - {@link addColumn} / {@link changeColumn} strip any column `references`.
+ * Enforce referential integrity in application code instead.
+ *
+ * CAVEAT — upserts: SingleStore's `ON DUPLICATE KEY UPDATE` uses the classic
+ * `VALUES(col)` reference, not the MySQL 8.0.19 row-alias form
+ * (`... AS new_row ... = new_row.col`) that the MySQL base emits. This dialect
+ * overrides {@link buildInsertQuery} / {@link buildUpsertQuery} to emit the
+ * `VALUES(col)` form.
+ *
+ * CAVEAT — unique constraints on columnstore tables must include the shard key;
+ * this is a SingleStore data-distribution rule that the ORM does not attempt to
+ * police.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SingleStoreDialect = void 0;
+const index_1 = require("../mysql/index");
+const prorm_1 = require("../../prorm");
+/**
+ * SingleStore dialect. Reuses the MySQL (`mysql2`) driver and all of
+ * MySQLDialect's behavior, overriding only the CREATE TABLE grammar that
+ * differs (storage kind, SHARD KEY, SORT KEY, clustered columnstore key,
+ * reference tables).
+ */
+class SingleStoreDialect extends index_1.MySQLDialect {
+    constructor(config) {
+        // SingleStore speaks the MySQL wire protocol on port 3306 by default.
+        super({ port: 3306, ...config });
+        this.name = 'singlestore';
+    }
+    /**
+     * Build the `CREATE TABLE` SQL string for SingleStore, synchronously.
+     *
+     * Exposed as a standalone (non-async, no I/O) method so the emitted grammar
+     * can be inspected/tested without a live connection. `createTable()` below
+     * delegates to it.
+     */
+    buildCreateTableSQL(tableName, columns, options) {
+        const opts = options || {};
+        const parts = [];
+        for (const [columnName, definition] of Object.entries(columns)) {
+            parts.push(this.buildColumnSQL(columnName, definition));
+        }
+        // Table-level constraints (PRIMARY KEY / UNIQUE / CHECK). FOREIGN KEY
+        // constraints are omitted — SingleStore does not support them (see the
+        // file header caveat and buildTableConstraintSQL).
+        if (opts.constraints) {
+            for (const constraint of opts.constraints) {
+                const sql = this.buildTableConstraintSQL(constraint);
+                if (sql)
+                    parts.push(sql);
+            }
+        }
+        // SHARD KEY (...) — distributed data-placement key. An empty array
+        // produces the keyless `SHARD KEY ()` form (random sharding).
+        if (opts.shardKey !== undefined) {
+            const cols = opts.shardKey.map((c) => this.escapeId(c)).join(', ');
+            parts.push(`SHARD KEY (${cols})`);
+        }
+        // SORT KEY (...) — columnstore ordering key.
+        if (opts.sortKey && opts.sortKey.length > 0) {
+            const cols = opts.sortKey.map((c) => this.escapeId(c)).join(', ');
+            parts.push(`SORT KEY (${cols})`);
+        }
+        // KEY (...) USING CLUSTERED COLUMNSTORE — explicit clustered columnstore key.
+        if (opts.columnstoreKey && opts.columnstoreKey.fields.length > 0) {
+            const cols = opts.columnstoreKey.fields.map((c) => this.escapeId(c)).join(', ');
+            parts.push(`KEY (${cols}) USING CLUSTERED COLUMNSTORE`);
+        }
+        // CREATE [ROWSTORE] [REFERENCE] TABLE [IF NOT EXISTS] name (...)
+        let sql = 'CREATE';
+        if (opts.rowstore) {
+            sql += ' ROWSTORE';
+        }
+        if (opts.reference) {
+            sql += ' REFERENCE';
+        }
+        sql += ' TABLE';
+        if (opts.ifNotExists) {
+            sql += ' IF NOT EXISTS';
+        }
+        sql += ` ${this.escapeId(tableName)} (${parts.join(', ')})`;
+        if (opts.charset) {
+            sql += ` DEFAULT CHARSET=${opts.charset}`;
+        }
+        if (opts.collate) {
+            sql += ` COLLATE ${opts.collate}`;
+        }
+        if (opts.comment) {
+            sql += ` COMMENT=${this.escape(opts.comment)}`;
+        }
+        return sql;
+    }
+    /**
+     * Create a new table using SingleStore grammar. Overrides MySQLDialect's
+     * createTable so shard/sort/columnstore keys and storage kind are honored.
+     */
+    async createTable(tableName, columns, options) {
+        await this.query(this.buildCreateTableSQL(tableName, columns, options));
+        // Secondary indexes are created after the table, same as the MySQL base.
+        if (options?.indexes) {
+            for (const index of options.indexes) {
+                await this.addIndex(tableName, index.name || `idx_${tableName}_${index.fields.join('_')}`, index.fields, {
+                    unique: index.unique,
+                    type: index.type,
+                    using: index.using,
+                    where: index.where,
+                    expression: index.expression,
+                    include: index.include,
+                });
+            }
+        }
+    }
+    /**
+     * Build a single column definition. Reimplemented here (rather than reusing
+     * MySQLDialect's private helper) using only public dialect methods, so the
+     * synchronous SQL builder stays self-contained.
+     */
+    buildColumnSQL(columnName, definition) {
+        let sql = `${this.escapeId(columnName)} ${this.getDataTypeSql(definition.type)}`;
+        if (definition.allowNull === false) {
+            sql += ' NOT NULL';
+        }
+        if (definition.defaultValue !== undefined) {
+            sql += ` DEFAULT ${this.formatDefaultValue(definition.defaultValue)}`;
+        }
+        if (definition.primaryKey) {
+            sql += ' PRIMARY KEY';
+        }
+        if (definition.autoIncrement) {
+            sql += ' AUTO_INCREMENT';
+        }
+        if (definition.unique) {
+            sql += typeof definition.unique === 'string'
+                ? ` UNIQUE KEY ${this.escapeId(definition.unique)}`
+                : ' UNIQUE';
+        }
+        if (definition.comment) {
+            sql += ` COMMENT ${this.escape(definition.comment)}`;
+        }
+        return sql;
+    }
+    /**
+     * Build a table-level constraint clause.
+     *
+     * SingleStore does NOT support FOREIGN KEY constraints — a real server
+     * rejects `FOREIGN KEY (...) REFERENCES ...` in CREATE TABLE with a syntax
+     * error. So FOREIGN KEY constraints are silently OMITTED here (the table is
+     * still created without the referential-integrity clause) rather than
+     * emitting SQL that would fail. PRIMARY KEY / UNIQUE / CHECK are supported
+     * and emitted normally.
+     */
+    buildTableConstraintSQL(constraint) {
+        const name = constraint.name ? `CONSTRAINT ${this.escapeId(constraint.name)} ` : '';
+        const fields = (constraint.fields || []).map((f) => this.escapeId(f)).join(', ');
+        switch (constraint.type) {
+            case 'PRIMARY KEY':
+                return `${name}PRIMARY KEY (${fields})`;
+            case 'UNIQUE':
+                return `${name}UNIQUE (${fields})`;
+            case 'CHECK':
+                return constraint.check ? `${name}CHECK (${constraint.check})` : null;
+            case 'FOREIGN KEY':
+                // SingleStore does not support foreign keys — omit the clause.
+                return null;
+            default:
+                return null;
+        }
+    }
+    /**
+     * Map an ORM DataType to SingleStore column SQL.
+     *
+     * SingleStore is largely MySQL-type-compatible, so the MySQL mapping is
+     * reused for everything EXCEPT geospatial types: SingleStore has a native
+     * `GEOGRAPHY` type (and `GEOGRAPHYPOINT`), whereas stock MySQL has no
+     * `GEOGRAPHY` type and the base dialect degrades it to `GEOMETRY`. Emit the
+     * native SingleStore type instead so geography columns round-trip correctly.
+     */
+    getDataTypeSql(dataType) {
+        if (dataType && typeof dataType === 'object') {
+            const dt = dataType;
+            if (dt.key === 'GEOGRAPHY') {
+                return 'GEOGRAPHY';
+            }
+        }
+        return super.getDataTypeSql(dataType);
+    }
+    /**
+     * Build an INSERT query.
+     *
+     * Overrides the MySQL base ONLY for the upsert (`ON DUPLICATE KEY UPDATE`)
+     * branch: the base uses the row-alias form (`... AS new_vals ON DUPLICATE
+     * KEY UPDATE col = new_vals.col`) introduced in MySQL 8.0.19, which
+     * SingleStore does not support. SingleStore uses the classic
+     * `VALUES(col)` reference instead. The plain (non-upsert) INSERT is
+     * identical to MySQL.
+     */
+    buildInsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const processedValues = [];
+        const placeholders = [];
+        for (const value of Object.values(values)) {
+            if (value instanceof prorm_1.Literal) {
+                placeholders.push(value.val);
+            }
+            else {
+                placeholders.push('?');
+                processedValues.push(value);
+            }
+        }
+        let sql = `INSERT INTO ${this.escapeId(tableName)} (${columns
+            .map((c) => this.escapeId(c))
+            .join(', ')}) VALUES (${placeholders.join(', ')})`;
+        if (options?.upsert) {
+            const updateFields = options.updateOnDuplicate && options.updateOnDuplicate.length > 0
+                ? options.updateOnDuplicate
+                : columns;
+            const updateColumns = updateFields
+                .map((c) => `${this.escapeId(c)} = VALUES(${this.escapeId(c)})`)
+                .join(', ');
+            sql += ` ON DUPLICATE KEY UPDATE ${updateColumns}`;
+        }
+        return { sql, values: processedValues };
+    }
+    /**
+     * Build an UPSERT query (`INSERT ... ON DUPLICATE KEY UPDATE`).
+     *
+     * Uses the classic `VALUES(col)` form rather than the MySQL 8.0.19 row-alias
+     * form the base emits, since SingleStore does not support the row alias.
+     * Like MySQL, SingleStore has no `RETURNING` clause, so a `returning`
+     * request fails fast.
+     */
+    buildUpsertQuery(tableName, values, options) {
+        const columns = Object.keys(values);
+        const processedValues = [];
+        const placeholders = [];
+        for (const value of Object.values(values)) {
+            if (value instanceof prorm_1.Literal) {
+                placeholders.push(value.val);
+            }
+            else {
+                placeholders.push('?');
+                processedValues.push(value);
+            }
+        }
+        const updateFields = options?.updateOnDuplicate && options.updateOnDuplicate.length > 0
+            ? options.updateOnDuplicate
+            : columns;
+        let sql = `INSERT INTO ${this.escapeId(tableName)} (${columns
+            .map((c) => this.escapeId(c))
+            .join(', ')}) VALUES (${placeholders.join(', ')})`;
+        const updateClauses = updateFields
+            .map((c) => `${this.escapeId(c)} = VALUES(${this.escapeId(c)})`)
+            .join(', ');
+        sql += ` ON DUPLICATE KEY UPDATE ${updateClauses}`;
+        if (options?.returning) {
+            throw new Error('SingleStore does not support the RETURNING clause. Re-fetch the row after the upsert instead.');
+        }
+        return { sql, values: processedValues };
+    }
+    /**
+     * Add a column. SingleStore does not support foreign keys, so any
+     * column-level `references` is stripped before delegating to the MySQL base
+     * (whose column builder would otherwise emit a `REFERENCES ...` clause that
+     * SingleStore rejects).
+     */
+    async addColumn(tableName, columnName, definition) {
+        return super.addColumn(tableName, columnName, this.stripReferences(definition));
+    }
+    /**
+     * Change a column. As with {@link addColumn}, any column-level `references`
+     * is stripped since SingleStore does not support foreign keys.
+     */
+    async changeColumn(tableName, columnName, definition) {
+        return super.changeColumn(tableName, columnName, this.stripReferences(definition));
+    }
+    /**
+     * SingleStore does not support foreign key constraints. Reject explicit
+     * foreign-key operations with a clear error rather than emitting SQL a real
+     * server would refuse.
+     */
+    async addForeignKey(_tableName, _columnName, _referencedTableName, _referencedColumnName, _options) {
+        throw new Error('SingleStore does not support foreign key constraints. Enforce referential integrity in application code instead.');
+    }
+    /**
+     * Create a constraint. PRIMARY KEY / UNIQUE / CHECK delegate to the MySQL
+     * base; FOREIGN KEY is rejected because SingleStore does not support it.
+     */
+    async createConstraint(tableName, constraintDef) {
+        if (constraintDef.type === 'FOREIGN KEY') {
+            throw new Error('SingleStore does not support foreign key constraints. Enforce referential integrity in application code instead.');
+        }
+        return super.createConstraint(tableName, constraintDef);
+    }
+    /** Return a shallow copy of the column definition without its `references`. */
+    stripReferences(definition) {
+        if (!definition.references) {
+            return definition;
+        }
+        const { references: _references, ...rest } = definition;
+        return rest;
+    }
+    /**
+     * Format a column DEFAULT value. Passes SQL functions (CURRENT_TIMESTAMP,
+     * etc.) and NULL through unquoted; everything else is escaped via the
+     * shared `escape()`.
+     */
+    formatDefaultValue(value) {
+        if (typeof value === 'string' &&
+            (value.toUpperCase().includes('CURRENT_') || value.toUpperCase() === 'NULL')) {
+            return value;
+        }
+        return this.escape(value);
+    }
+}
+exports.SingleStoreDialect = SingleStoreDialect;