ts-prorm-orm 1.1.0

package/dist/decorators/check.js

@@ -0,0 +1,435 @@
+"use strict";
+/**
+ * @Check decorator for the ORM — generates CHECK constraints without writing raw SQL.
+ *
+ * Supports ORM-native operator syntax that gets converted to SQL CHECK expressions.
+ *
+ * Usage Examples:
+ *
+ * // Column-level check with ORM operators
+ * @Check({ age: { $gte: 18 } })
+ * age: number;
+ *
+ * // Multiple column checks
+ * @Check({
+ *   status: { $in: ['active', 'pending', 'draft'] },
+ *   email: { $regex: '^[^@]+@[^@]+$' }
+ * })
+ * email: string;
+ *
+ * // Custom condition with message
+ * @Check({
+ *   condition: (row) => row.startDate < row.endDate,
+ *   message: 'Start date must be before end date'
+ * })
+ * startDate: Date;
+ *
+ * // Column-level check (explicit column)
+ * @CheckColumn('price', { $gte: 0 }, 'Price must be positive')
+ * @CheckColumn('quantity', { $gt: 0 }, 'Quantity must be greater than zero')
+ *
+ * // Table-level check (multiple columns)
+ * @CheckTable({
+ *   condition: (row) => row.quantity * row.price >= row.minimumOrder,
+ *   message: 'Total must meet minimum order amount'
+ * })
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.operatorToSQL = operatorToSQL;
+exports.Check = Check;
+exports.CheckColumn = CheckColumn;
+exports.CheckTable = CheckTable;
+exports.getCheckConstraints = getCheckConstraints;
+exports.getTableCheckConstraints = getTableCheckConstraints;
+exports.getAllCheckConstraints = getAllCheckConstraints;
+exports.buildCheckConstraintSQL = buildCheckConstraintSQL;
+exports.buildAllCheckConstraints = buildAllCheckConstraints;
+exports.clearCheckConstraints = clearCheckConstraints;
+// ==================== Metadata Keys ====================
+const CHECK_CONSTRAINTS_KEY = '__orm_check_constraints__';
+const TABLE_CHECK_CONSTRAINTS_KEY = '__orm_table_check_constraints__';
+// ==================== SQL Generation ====================
+/**
+ * Escape SQL string value for use in CHECK constraints
+ */
+function escapeSQLValue(value) {
+    if (value === null)
+        return 'NULL';
+    if (typeof value === 'number')
+        return String(value);
+    if (typeof value === 'boolean')
+        return value ? 'TRUE' : 'FALSE';
+    if (typeof value === 'string')
+        return `'${value.replace(/'/g, "''")}'`;
+    if (Array.isArray(value)) {
+        return value.map((v) => escapeSQLValue(v)).join(', ');
+    }
+    // For objects, serialize as JSON
+    return `'${JSON.stringify(value).replace(/'/g, "''")}'`;
+}
+/**
+ * Throw if the given operator is used with a non-Postgres dialect.
+ * These operators map directly to PostgreSQL jsonb/array operators
+ * (@>, <@, &&) that have no CHECK-constraint-safe equivalent elsewhere.
+ */
+function assertPostgres(dialect, opName) {
+    if (dialect !== 'postgres') {
+        throw new Error(`Operator "${opName}" generates PostgreSQL-specific jsonb/array syntax and is not supported for the "${dialect}" dialect.`);
+    }
+}
+/**
+ * Build a case-insensitive LIKE expression appropriate for the target dialect.
+ *
+ * - PostgreSQL: native ILIKE / NOT ILIKE
+ * - SQLite: LIKE with COLLATE NOCASE (SQLite has no ILIKE keyword)
+ * - MySQL/MariaDB: plain LIKE — the default collation (e.g. utf8mb4_general_ci)
+ *   is already case-insensitive, so no special-casing is required
+ * - MSSQL: plain LIKE — default (non-binary) collations are case-insensitive
+ * - Oracle: case-sensitive by default, so wrap both sides in UPPER()
+ */
+function buildCaseInsensitiveLike(quotedField, value, dialect, negate) {
+    const escapedValue = escapeSQLValue(value);
+    switch (dialect) {
+        case 'postgres':
+            return `${quotedField} ${negate ? 'NOT ILIKE' : 'ILIKE'} ${escapedValue}`;
+        case 'sqlite':
+            return `${quotedField} ${negate ? 'NOT LIKE' : 'LIKE'} ${escapedValue} COLLATE NOCASE`;
+        case 'oracle':
+            return `UPPER(${quotedField}) ${negate ? 'NOT LIKE' : 'LIKE'} UPPER(${escapedValue})`;
+        case 'mysql':
+        case 'mariadb':
+        case 'mssql':
+        default:
+            // Case-insensitive by default collation on these dialects
+            return `${quotedField} ${negate ? 'NOT LIKE' : 'LIKE'} ${escapedValue}`;
+    }
+}
+/**
+ * Build a regex-match expression appropriate for the target dialect.
+ *
+ * - PostgreSQL: ~ / !~ (case-sensitive), ~* / !~* (case-insensitive)
+ * - MySQL/MariaDB: REGEXP / NOT REGEXP (MySQL's REGEXP is case-insensitive
+ *   by default under the standard case-insensitive collations, so it is
+ *   used for both $regex and $iRegexp)
+ * - Oracle: REGEXP_LIKE(field, pattern[, 'i']) function, wrapped with NOT for negation
+ * - SQLite: no REGEXP function is registered by this ORM's SQLite dialect
+ *   (see src/dialects/sqlite/index.ts), so regex CHECK constraints would
+ *   fail at runtime — throw a clear error instead of emitting invalid SQL
+ * - MSSQL: has no native regex support in T-SQL — throw a clear error
+ */
+function buildRegexExpression(quotedField, value, dialect, opts) {
+    const escapedValue = escapeSQLValue(value);
+    const { negate, ci } = opts;
+    switch (dialect) {
+        case 'postgres': {
+            const op = ci ? (negate ? '!~*' : '~*') : negate ? '!~' : '~';
+            return `${quotedField} ${op} ${escapedValue}`;
+        }
+        case 'mysql':
+        case 'mariadb': {
+            const op = negate ? 'NOT REGEXP' : 'REGEXP';
+            return `${quotedField} ${op} ${escapedValue}`;
+        }
+        case 'oracle': {
+            const modifier = ci ? `, 'i'` : '';
+            const expr = `REGEXP_LIKE(${quotedField}, ${escapedValue}${modifier})`;
+            return negate ? `NOT ${expr}` : expr;
+        }
+        case 'sqlite':
+            throw new Error('Regex CHECK constraints are not supported for the "sqlite" dialect: no REGEXP function is registered.');
+        case 'mssql':
+        default:
+            throw new Error(`Regex CHECK constraints are not supported for the "${dialect}" dialect.`);
+    }
+}
+/**
+ * Convert ORM operator to SQL CHECK expression
+ * @param fieldName - The column name
+ * @param operator - The ORM operator object
+ * @param dialect - The target SQL dialect (defaults to 'postgres' for backwards compatibility)
+ * @returns SQL expression string
+ */
+function operatorToSQL(fieldName, operator, dialect = 'postgres') {
+    const opKeys = Object.keys(operator);
+    const opKey = opKeys[0];
+    const value = operator[opKey];
+    // Wrap field name in quotes for safety
+    const quotedField = `"${fieldName}"`;
+    switch (opKey) {
+        case '$eq':
+            return `${quotedField} = ${escapeSQLValue(value)}`;
+        case '$ne':
+            return `${quotedField} <> ${escapeSQLValue(value)}`;
+        case '$gt':
+            return `${quotedField} > ${escapeSQLValue(value)}`;
+        case '$gte':
+            return `${quotedField} >= ${escapeSQLValue(value)}`;
+        case '$lt':
+            return `${quotedField} < ${escapeSQLValue(value)}`;
+        case '$lte':
+            return `${quotedField} <= ${escapeSQLValue(value)}`;
+        case '$in':
+            if (!Array.isArray(value) || value.length === 0) {
+                throw new Error('$in operator requires a non-empty array');
+            }
+            return `${quotedField} IN (${value.map((v) => escapeSQLValue(v)).join(', ')})`;
+        case '$notIn':
+            if (!Array.isArray(value) || value.length === 0) {
+                throw new Error('$notIn operator requires a non-empty array');
+            }
+            return `${quotedField} NOT IN (${value.map((v) => escapeSQLValue(v)).join(', ')})`;
+        case '$between':
+            if (!Array.isArray(value) || value.length !== 2) {
+                throw new Error('$between operator requires an array of exactly 2 values');
+            }
+            return `${quotedField} BETWEEN ${escapeSQLValue(value[0])} AND ${escapeSQLValue(value[1])}`;
+        case '$notBetween':
+            if (!Array.isArray(value) || value.length !== 2) {
+                throw new Error('$notBetween operator requires an array of exactly 2 values');
+            }
+            return `${quotedField} NOT BETWEEN ${escapeSQLValue(value[0])} AND ${escapeSQLValue(value[1])}`;
+        case '$like':
+            return `${quotedField} LIKE ${escapeSQLValue(value)}`;
+        case '$notLike':
+            return `${quotedField} NOT LIKE ${escapeSQLValue(value)}`;
+        case '$iLike':
+            return buildCaseInsensitiveLike(quotedField, value, dialect, false);
+        case '$notILike':
+            return buildCaseInsensitiveLike(quotedField, value, dialect, true);
+        case '$regex':
+            return buildRegexExpression(quotedField, value, dialect, { negate: false, ci: false });
+        case '$notRegexp':
+            return buildRegexExpression(quotedField, value, dialect, { negate: true, ci: false });
+        case '$iRegexp':
+            return buildRegexExpression(quotedField, value, dialect, { negate: false, ci: true });
+        case '$notIRegexp':
+            return buildRegexExpression(quotedField, value, dialect, { negate: true, ci: true });
+        case '$isNull':
+            return `${quotedField} IS NULL`;
+        case '$isNotNull':
+            return `${quotedField} IS NOT NULL`;
+        case '$contains':
+            // PostgreSQL jsonb/array containment operator — no equivalent elsewhere
+            assertPostgres(dialect, '$contains');
+            return `${quotedField} @> ${escapeSQLValue(value)}`;
+        case '$containedBy':
+            // PostgreSQL jsonb/array containment operator — no equivalent elsewhere
+            assertPostgres(dialect, '$containedBy');
+            return `${quotedField} <@ ${escapeSQLValue(value)}`;
+        case '$overlap':
+            // PostgreSQL array overlap operator — no equivalent elsewhere
+            assertPostgres(dialect, '$overlap');
+            return `${quotedField} && ${escapeSQLValue(value)}`;
+        default:
+            throw new Error(`Unsupported operator: ${opKey}`);
+    }
+}
+/**
+ * Generate a CHECK constraint name
+ */
+function generateCheckName(tableName, fieldName) {
+    const timestamp = Date.now().toString(36).slice(-6);
+    if (fieldName) {
+        return `chk_${tableName}_${fieldName}_${timestamp}`;
+    }
+    return `chk_${tableName}_table_${timestamp}`;
+}
+/**
+ * Parse condition function to SQL (simple implementation)
+ * This handles common patterns for row-level checks
+ */
+function conditionToSQL(condition, paramNames) {
+    // Get the function source code
+    const funcStr = condition.toString();
+    // Extract parameter names if not provided
+    const params = paramNames.length > 0 ? paramNames : ['row'];
+    // Simple pattern matching for common expressions
+    // This is a basic implementation - complex conditions may need manual SQL
+    // Handle simple comparisons: row.a < row.b
+    const simpleCompare = funcStr.match(/row\.(\w+)\s*([<>]=?)\s*row\.(\w+)/);
+    if (simpleCompare) {
+        return `"${simpleCompare[1]}" ${simpleCompare[2]} "${simpleCompare[3]}"`;
+    }
+    // Handle arithmetic: row.a * row.b >= row.c
+    const arithmeticCompare = funcStr.match(/row\.(\w+)\s*([*\/+-])\s*row\.(\w+)\s*(>=?|<=?|==|!=)\s*row\.(\w+)/);
+    if (arithmeticCompare) {
+        return `"${arithmeticCompare[1]}" ${arithmeticCompare[2]} "${arithmeticCompare[3]}" ${arithmeticCompare[4]} "${arithmeticCompare[5]}"`;
+    }
+    // Handle: row.field < value (constant)
+    const fieldValueCompare = funcStr.match(/row\.(\w+)\s*(>=?|<=?|==|!=)\s*(\d+)/);
+    if (fieldValueCompare) {
+        return `"${fieldValueCompare[1]}" ${fieldValueCompare[2]} ${fieldValueCompare[3]}`;
+    }
+    // Handle: value < row.field (constant)
+    const valueFieldCompare = funcStr.match(/(\d+)\s*(>=?|<=?|==|!=)\s*row\.(\w+)/);
+    if (valueFieldCompare) {
+        return `${valueFieldCompare[1]} ${valueFieldCompare[2]} "${valueFieldCompare[3]}"`;
+    }
+    // Fallback: for complex conditions, throw an error suggesting manual SQL
+    throw new Error('Complex CHECK conditions require manual SQL. Use @ColumnConstraint with type: "check" and explicit check string.');
+}
+// ==================== Decorators ====================
+/**
+ * @Check decorator — attach CHECK constraints to a column or multiple columns.
+ *
+ * For column-level use (on class property):
+ * @Check({ age: { $gte: 18 } })
+ * age: number;
+ *
+ * For multiple checks:
+ * @Check({
+ *   status: { $in: ['active', 'pending'] },
+ *   email: { $regex: '^[^@]+@[^@]+$' }
+ * })
+ * email: string;
+ *
+ * For row-level condition:
+ * @Check({
+ *   condition: (row) => row.startDate < row.endDate,
+ *   message: 'Start date must be before end date'
+ * })
+ * startDate: Date;
+ */
+function Check(options) {
+    return (target, propertyKey) => {
+        const fieldName = String(propertyKey);
+        if (!target[CHECK_CONSTRAINTS_KEY]) {
+            target[CHECK_CONSTRAINTS_KEY] = [];
+        }
+        const constraints = target[CHECK_CONSTRAINTS_KEY];
+        // Check if this is a row-level condition (condition function)
+        if ('condition' in options) {
+            const rowCheck = options;
+            constraints.push({
+                type: 'table',
+                name: '',
+                condition: rowCheck.condition,
+                message: rowCheck.message,
+            });
+        }
+        else {
+            // Field-level checks
+            for (const [field, operator] of Object.entries(options)) {
+                if ((typeof operator === 'object' && '$eq' in operator) || '$gte' in operator) {
+                    // Skip if it's a special property, not a field check
+                    if (field === 'condition' || field === 'message')
+                        continue;
+                }
+                if (typeof operator === 'object' && operator !== null) {
+                    constraints.push({
+                        type: 'column',
+                        name: '',
+                        field: field,
+                        operator: operator,
+                    });
+                }
+            }
+        }
+    };
+}
+/**
+ * @CheckColumn decorator — explicit column-level CHECK constraint.
+ *
+ * @CheckColumn('price', { $gte: 0 }, 'Price must be positive')
+ * price: number;
+ */
+function CheckColumn(column, operator, message) {
+    return (target, propertyKey) => {
+        if (!target[CHECK_CONSTRAINTS_KEY]) {
+            target[CHECK_CONSTRAINTS_KEY] = [];
+        }
+        target[CHECK_CONSTRAINTS_KEY].push({
+            type: 'column',
+            name: '',
+            field: column,
+            operator,
+            message,
+        });
+    };
+}
+/**
+ * @CheckTable decorator — table-level CHECK constraint with multi-column conditions.
+ *
+ * @CheckTable({
+ *   condition: (row) => row.quantity * row.price >= row.minimumOrder,
+ *   message: 'Total must meet minimum order amount'
+ * })
+ */
+function CheckTable(options) {
+    return (target) => {
+        if (!target[TABLE_CHECK_CONSTRAINTS_KEY]) {
+            target[TABLE_CHECK_CONSTRAINTS_KEY] = [];
+        }
+        target[TABLE_CHECK_CONSTRAINTS_KEY].push({
+            type: 'table',
+            name: options.name || '',
+            condition: options.condition,
+            message: options.message,
+        });
+    };
+}
+// ==================== Helpers ====================
+/**
+ * Get all CHECK constraints from a model class or instance
+ */
+function getCheckConstraints(target) {
+    return target[CHECK_CONSTRAINTS_KEY] || [];
+}
+/**
+ * Get all table-level CHECK constraints from a model class
+ */
+function getTableCheckConstraints(target) {
+    return target[TABLE_CHECK_CONSTRAINTS_KEY] || [];
+}
+/**
+ * Get all CHECK constraints (both column and table level)
+ */
+function getAllCheckConstraints(target) {
+    return [...getCheckConstraints(target), ...getTableCheckConstraints(target)];
+}
+/**
+ * Build CREATE TABLE CHECK constraint SQL
+ */
+function buildCheckConstraintSQL(tableName, constraint, dialect = 'postgres') {
+    const name = constraint.name || generateCheckName(tableName, constraint.field);
+    if (constraint.type === 'column' && constraint.operator && constraint.field) {
+        const sqlExpr = operatorToSQL(constraint.field, constraint.operator, dialect);
+        return `CONSTRAINT "${name}" CHECK (${sqlExpr})`;
+    }
+    if (constraint.type === 'table' && constraint.condition) {
+        // Extract field names from the model
+        const fields = extractFieldNames(constraint.condition);
+        const sqlExpr = conditionToSQL(constraint.condition, fields);
+        return `CONSTRAINT "${name}" CHECK (${sqlExpr})`;
+    }
+    // If sql is already provided (manual SQL), use it directly
+    if (constraint.sql) {
+        return `CONSTRAINT "${name}" CHECK (${constraint.sql})`;
+    }
+    throw new Error('Invalid check constraint: missing operator or condition');
+}
+/**
+ * Extract parameter names from a condition function
+ */
+function extractFieldNames(condition) {
+    const funcStr = condition.toString();
+    const fieldMatches = funcStr.match(/row\.(\w+)/g);
+    if (!fieldMatches)
+        return [];
+    return [...new Set(fieldMatches.map((m) => m.replace('row.', '')))];
+}
+/**
+ * Build all CHECK constraints for a table
+ */
+function buildAllCheckConstraints(tableName, constraints, dialect = 'postgres') {
+    return constraints
+        .filter((c) => c.type === 'column' || c.type === 'table')
+        .map((c) => buildCheckConstraintSQL(tableName, c, dialect));
+}
+/**
+ * Clear CHECK constraints (useful for testing)
+ */
+function clearCheckConstraints(target) {
+    delete target[CHECK_CONSTRAINTS_KEY];
+    delete target[TABLE_CHECK_CONSTRAINTS_KEY];
+}