ts-prorm-orm 1.1.0

package/dist/decorators/uuid.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * UUID Decorator for the ORM
+ *
+ * Provides PostgreSQL UUID type support with automatic extension management.
+ * Requires: CREATE EXTENSION IF NOT EXISTS "uuid-ossp"
+ *
+ * Usage:
+ *
+ *   // Auto-generate UUID using gen_random_uuid() (PostgreSQL 13+)
+ *   @UUID()
+ *   id: string;
+ *
+ *   // Use uuid_generate_v4() (requires uuid-ossp extension)
+ *   @UUID({ defaultValue: 'uuid_generate_v4' })
+ *   id: string;
+ *
+ *   // With custom default
+ *   @UUID({ defaultValue: 'gen_random_uuid' })
+ *   id: string;
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UUID = UUID;
+exports.getUUIDMetadata = getUUIDMetadata;
+exports.getAllUUIDMetadata = getAllUUIDMetadata;
+exports.isUUIDColumn = isUUIDColumn;
+exports.clearUUIDMetadata = clearUUIDMetadata;
+exports.getUUIDExtensionSQL = getUUIDExtensionSQL;
+exports.buildUUIDDefaultSQL = buildUUIDDefaultSQL;
+// ==================== Registry ====================
+const uuidMetadataMap = new Map();
+/**
+ * UUID decorator for PostgreSQL UUID columns
+ *
+ * @param options - Optional UUID column options
+ *
+ * @example
+ * // Auto-generate UUID
+ * class User extends Model {
+ *   @UUID()
+ *   id: string;
+ * }
+ *
+ * // With specific default
+ * class User extends Model {
+ *   @UUID({ defaultValue: 'uuid_generate_v4' })
+ *   id: string;
+ * }
+ */
+function UUID(options) {
+    return function (target, propertyKey) {
+        const decoratorOptions = {
+            allowNull: false,
+            defaultValue: 'gen_random_uuid',
+            ...options,
+        };
+        // Get or create metadata map for this class
+        if (!uuidMetadataMap.has(target.constructor)) {
+            uuidMetadataMap.set(target.constructor, new Map());
+        }
+        const metadataMap = uuidMetadataMap.get(target.constructor);
+        // Store metadata
+        metadataMap.set(propertyKey, {
+            options: decoratorOptions,
+        });
+    };
+}
+/**
+ * Get UUID metadata for a property
+ *
+ * @param target - The target class
+ * @param propertyKey - The property name
+ * @returns UUID metadata or undefined if not found
+ */
+function getUUIDMetadata(target, propertyKey) {
+    const metadataMap = uuidMetadataMap.get(target.constructor);
+    if (!metadataMap) {
+        return undefined;
+    }
+    return metadataMap.get(propertyKey);
+}
+/**
+ * Get all UUID metadata for a class
+ *
+ * @param target - The target class
+ * @returns Map of property names to UUID metadata
+ */
+function getAllUUIDMetadata(target) {
+    return uuidMetadataMap.get(target.constructor) || new Map();
+}
+/**
+ * Check if a property is a UUID column
+ *
+ * @param target - The target class
+ * @param propertyKey - The property name
+ * @returns True if the property is a UUID column
+ */
+function isUUIDColumn(target, propertyKey) {
+    const metadata = getUUIDMetadata(target, propertyKey);
+    return metadata !== undefined;
+}
+/**
+ * Clear UUID metadata (useful for testing)
+ */
+function clearUUIDMetadata() {
+    uuidMetadataMap.clear();
+}
+/**
+ * Get the SQL to create the UUID extension
+ *
+ * @returns SQL to create the uuid-ossp extension
+ */
+function getUUIDExtensionSQL() {
+    return 'CREATE EXTENSION IF NOT EXISTS "uuid-ossp"';
+}
+/**
+ * Build the default value SQL for UUID
+ *
+ * @param options - UUID decorator options
+ * @returns SQL for the default value
+ */
+function buildUUIDDefaultSQL(options) {
+    if (!options.defaultValue) {
+        return undefined;
+    }
+    switch (options.defaultValue) {
+        case 'gen_random_uuid':
+            return 'gen_random_uuid()';
+        case 'uuid_generate_v4':
+            return 'uuid_generate_v4()';
+        default:
+            // Custom SQL expression
+            return options.defaultValue;
+    }
+}

package/dist/decorators/view.js

@@ -0,0 +1,258 @@
+"use strict";
+/**
+ * @View class decorator — annotate a Model class so it maps to a database view
+ * instead of a base table. The ORM stores the view definition and can generate
+ * the CREATE VIEW DDL for you.
+ *
+ * Example:
+ *
+ *   @View({
+ *     name: 'active_users_view',
+ *     query: `
+ *       SELECT id, name, email, created_at
+ *       FROM users
+ *       WHERE status = 'active'
+ *     `,
+ *     replace: true,
+ *   })
+ *   class ActiveUser extends Model<ActiveUserAttributes> {
+ *     declare id: number;
+ *     declare name: string;
+ *     declare email: string;
+ *     declare createdAt: Date;
+ *   }
+ *
+ *   // After Model.init() — generate and create the view:
+ *   const sql = ViewRegistry.getSQL(ActiveUser);
+ *   await prorm.query(sql);
+ *
+ *   // Or let the ORM create it automatically:
+ *   await ViewRegistry.createView(prorm, ActiveUser);
+ *
+ *   // Query it just like a normal model:
+ *   const users = await ActiveUser.findAll({ where: { name: 'Alice' } });
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaterializedViewRegistry = exports.ViewRegistry = void 0;
+exports.getViewOptions = getViewOptions;
+exports.View = View;
+exports.getMaterializedViewOptions = getMaterializedViewOptions;
+exports.MaterializedView = MaterializedView;
+// ==================== Registry ====================
+const VIEW_OPTIONS_KEY = '__orm_view_options__';
+/**
+ * Read the @View options attached to a class.
+ * Returns undefined if the class has no @View decorator.
+ */
+function getViewOptions(target) {
+    return target[VIEW_OPTIONS_KEY];
+}
+// ==================== Decorator ====================
+/**
+ * Mark a Model subclass as a database view.
+ *
+ * - Sets the `tableName` option to the view name so findAll() etc. work correctly.
+ * - Registers view metadata so the ORM can generate CREATE VIEW DDL.
+ *
+ *   @View({ name: 'active_users_view', query: 'SELECT ...' })
+ *   class ActiveUser extends Model { ... }
+ */
+function View(options) {
+    return function (target) {
+        // Resolve view name — default: class name converted to snake_case
+        const name = options.name ?? toSnakeCase(target.name);
+        const resolved = {
+            dialect: 'mysql',
+            replace: false,
+            ...options,
+            name,
+        };
+        target[VIEW_OPTIONS_KEY] = resolved;
+    };
+}
+// ==================== SQL Generation ====================
+function qualifiedName(name, schema, dialect) {
+    if (!schema)
+        return dialect === 'postgres' ? `"${name}"` : `\`${name}\``;
+    return dialect === 'postgres' ? `"${schema}"."${name}"` : `\`${schema}\`.\`${name}\``;
+}
+function buildViewSQL(opts) {
+    const query = opts.queryFn ? opts.queryFn() : opts.query;
+    if (!query)
+        throw new Error('[ORM] @View requires either a `query` or `queryFn` option.');
+    const dialect = opts.dialect ?? 'mysql';
+    const name = qualifiedName(opts.name, opts.schema, dialect);
+    const materialized = opts.materialized ? 'MATERIALIZED ' : '';
+    const orReplace = opts.replace && !opts.materialized ? 'OR REPLACE ' : '';
+    if (dialect === 'postgres') {
+        let sql = `CREATE ${orReplace}${materialized}VIEW ${name} AS\n${query.trim()}`;
+        if (opts.checkOption && !opts.materialized) {
+            const check = opts.checkOption === true ? 'CASCADED' : opts.checkOption;
+            sql += `\nWITH ${check} CHECK OPTION`;
+        }
+        return sql;
+    }
+    // MySQL / MariaDB / SQLite
+    return `CREATE ${orReplace}VIEW ${name} AS\n${query.trim()}`;
+}
+// ==================== Public Registry API ====================
+exports.ViewRegistry = {
+    /**
+     * Generate the CREATE VIEW SQL for a @View-annotated class.
+     */
+    getSQL(target, dialectOverride) {
+        const opts = getViewOptions(target);
+        if (!opts)
+            throw new Error(`[ORM] Class "${target.name}" does not have a @View decorator.`);
+        return buildViewSQL({ ...opts, ...(dialectOverride ? { dialect: dialectOverride } : {}) });
+    },
+    /**
+     * Execute the CREATE VIEW statement for a @View-annotated model class.
+     */
+    async createView(prorm, target, dialectOverride) {
+        const sql = exports.ViewRegistry.getSQL(target, dialectOverride);
+        await prorm.query(sql);
+    },
+    /**
+     * Drop the view for a @View-annotated class.
+     * @param ifExists - Emit IF EXISTS (default: true)
+     */
+    async dropView(prorm, target, ifExists = true) {
+        const opts = getViewOptions(target);
+        if (!opts)
+            throw new Error(`[ORM] Class "${target.name}" does not have a @View decorator.`);
+        const dialect = opts.dialect ?? 'mysql';
+        const name = qualifiedName(opts.name, opts.schema, dialect);
+        const ifExistsClause = ifExists ? 'IF EXISTS ' : '';
+        const materialized = opts.materialized ? 'MATERIALIZED ' : '';
+        await prorm.query(`DROP ${materialized}VIEW ${ifExistsClause}${name}`);
+    },
+};
+const MATERIALIZED_VIEW_OPTIONS_KEY = '__orm_materialized_view_options__';
+/**
+ * Read the @MaterializedView options attached to a class.
+ * Returns undefined if the class has no @MaterializedView decorator.
+ */
+function getMaterializedViewOptions(target) {
+    return target[MATERIALIZED_VIEW_OPTIONS_KEY];
+}
+/**
+ * Mark a Model subclass as a database materialized view.
+ *
+ * - Sets the `tableName` option to the view name so findAll() etc. work correctly.
+ * - Registers materialized view metadata so the ORM can generate CREATE MATERIALIZED VIEW DDL.
+ * - Adds a `refresh()` static method for refreshing the view data.
+ *
+ *   @MaterializedView({
+ *     name: 'user_stats_view',
+ *     query: `
+ *       SELECT user_id, COUNT(*) as order_count
+ *       FROM orders
+ *       GROUP BY user_id
+ *     `,
+ *     uniqueIndex: 'user_stats_view_user_id_key',
+ *   })
+ *   class UserStats extends Model<UserStatsAttributes> {
+ *     declare userId: number;
+ *     declare orderCount: number;
+ *   }
+ *
+ *   // After Model.init() — generate and create the materialized view:
+ *   const sql = MaterializedViewRegistry.getSQL(UserStats);
+ *   await prorm.query(sql);
+ *
+ *   // Or let the ORM create it automatically:
+ *   await MaterializedViewRegistry.createMaterializedView(prorm, UserStats);
+ *
+ *   // Query it just like a normal model:
+ *   const stats = await UserStats.findAll();
+ *
+ *   // Refresh the materialized view:
+ *   await UserStats.refresh();
+ *   // Or concurrently (requires unique index):
+ *   await UserStats.refresh({ concurrently: true });
+ */
+function MaterializedView(options) {
+    return function (target) {
+        // Resolve view name — default: class name converted to snake_case
+        const name = options.name ?? toSnakeCase(target.name);
+        const resolved = {
+            refreshStrategy: 'ON DEMAND',
+            withData: true,
+            replace: false,
+            ifNotExists: false,
+            ...options,
+            name,
+        };
+        target[MATERIALIZED_VIEW_OPTIONS_KEY] = resolved;
+        // Mark as materialized view for type checking
+        target.isMaterializedView = true;
+    };
+}
+// ==================== SQL Generation for Materialized Views ====================
+function buildMaterializedViewSQL(opts) {
+    const query = opts.queryFn ? opts.queryFn() : opts.query;
+    if (!query)
+        throw new Error('[ORM] @MaterializedView requires either a `query` or `queryFn` option.');
+    const name = qualifiedName(opts.name, opts.schema, 'postgres');
+    let sql = 'CREATE MATERIALIZED VIEW';
+    if (opts.replace) {
+        sql = 'CREATE OR REPLACE MATERIALIZED VIEW';
+    }
+    else if (opts.ifNotExists) {
+        sql = 'CREATE MATERIALIZED VIEW IF NOT EXISTS';
+    }
+    sql += ` ${name} AS\n${query.trim()}`;
+    if (!opts.withData) {
+        sql += ' WITH NO DATA';
+    }
+    return sql;
+}
+// ==================== Materialized View Registry ====================
+exports.MaterializedViewRegistry = {
+    /**
+     * Generate the CREATE MATERIALIZED VIEW SQL for a @MaterializedView-annotated class.
+     */
+    getSQL(target, dialectOverride) {
+        const opts = getMaterializedViewOptions(target);
+        if (!opts)
+            throw new Error(`[ORM] Class "${target.name}" does not have a @MaterializedView decorator.`);
+        return buildMaterializedViewSQL({
+            ...opts,
+            ...(dialectOverride ? { schema: dialectOverride } : {}),
+        });
+    },
+    /**
+     * Execute the CREATE MATERIALIZED VIEW statement for a @MaterializedView-annotated model class.
+     */
+    async createMaterializedView(prorm, target, dialectOverride) {
+        const sql = exports.MaterializedViewRegistry.getSQL(target, dialectOverride);
+        await prorm.query(sql);
+        // Create unique index if provided (required for CONCURRENTLY refresh)
+        const opts = getMaterializedViewOptions(target);
+        if (opts?.uniqueIndex) {
+            const name = qualifiedName(opts.name, opts.schema, 'postgres');
+            const indexSql = `CREATE UNIQUE INDEX ${opts.uniqueIndex} ON ${name} (${opts.uniqueIndex.replace(/_key$/, '')})`;
+            await prorm.query(indexSql);
+        }
+    },
+    /**
+     * Drop the materialized view for a @MaterializedView-annotated class.
+     * @param ifExists - Emit IF EXISTS (default: true)
+     */
+    async dropMaterializedView(prorm, target, ifExists = true) {
+        const opts = getMaterializedViewOptions(target);
+        if (!opts)
+            throw new Error(`[ORM] Class "${target.name}" does not have a @MaterializedView decorator.`);
+        const name = qualifiedName(opts.name, opts.schema, 'postgres');
+        const ifExistsClause = ifExists ? 'IF EXISTS ' : '';
+        await prorm.query(`DROP MATERIALIZED VIEW ${ifExistsClause}${name}`);
+    },
+};
+// ==================== Internal Helpers ====================
+function toSnakeCase(str) {
+    return str
+        .replace(/([A-Z])/g, '_$1')
+        .toLowerCase()
+        .replace(/^_/, '');
+}