ts-prorm-orm 1.1.0

package/dist/decorators/foreign-table.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForeignTableRegistry = void 0;
+exports.setForeignTableRedisClient = setForeignTableRedisClient;
+exports.getForeignTableRedisClient = getForeignTableRedisClient;
+exports.ForeignTable = ForeignTable;
+exports.getForeignTableOptions = getForeignTableOptions;
+exports.isForeignTable = isForeignTable;
+exports.cacheForeignTableOptions = cacheForeignTableOptions;
+exports.getCachedForeignTableOptions = getCachedForeignTableOptions;
+exports.invalidateForeignTableCache = invalidateForeignTableCache;
+exports.warmupForeignTableCache = warmupForeignTableCache;
+let globalRedisClient = null;
+function setForeignTableRedisClient(client) {
+    globalRedisClient = client;
+}
+function getForeignTableRedisClient() {
+    return globalRedisClient;
+}
+const FOREIGN_TABLE_KEY = '__orm_foreign_table__';
+function ForeignTable(options) {
+    return function (target) {
+        const resolved = {
+            server: options.server,
+            foreignSchema: options.foreignSchema,
+            options: options.options,
+            userMappings: options.userMappings,
+            columns: options.columns,
+            ifNotExists: options.ifNotExists ?? true,
+            schema: options.schema ?? 'public',
+            cache: {
+                redis: options.cache?.redis ?? true,
+                ttl: options.cache?.ttl ?? 3600,
+                keyPrefix: options.cache?.keyPrefix ?? 'orm:foreign-table',
+            },
+        };
+        target[FOREIGN_TABLE_KEY] = resolved;
+    };
+}
+function getForeignTableOptions(target) {
+    return target[FOREIGN_TABLE_KEY];
+}
+function isForeignTable(target) {
+    return !!target[FOREIGN_TABLE_KEY];
+}
+function getCacheKey(target, prefix = 'orm:foreign-table') {
+    return prefix + ':' + target.name;
+}
+function serializeOptions(opts) {
+    return JSON.stringify(opts);
+}
+function deserializeOptions(data) {
+    return JSON.parse(data);
+}
+async function cacheForeignTableOptions(target, options) {
+    const opts = options ?? getForeignTableOptions(target);
+    if (!opts)
+        throw new Error('[ORM] Class ' + target.name + ' does not have @ForeignTable decorator.');
+    const cacheConfig = opts.cache;
+    if (!cacheConfig?.redis)
+        return;
+    const redis = globalRedisClient;
+    if (!redis) {
+        console.warn('[ORM] Redis client not configured, skipping cache write.');
+        return;
+    }
+    const key = getCacheKey(target, cacheConfig.keyPrefix);
+    const ttl = cacheConfig.ttl ?? 3600;
+    await redis.set(key, serializeOptions(opts), 'EX', ttl);
+}
+async function getCachedForeignTableOptions(target) {
+    const opts = getForeignTableOptions(target);
+    if (!opts)
+        return null;
+    const cacheConfig = opts.cache;
+    if (!cacheConfig?.redis)
+        return null;
+    const redis = globalRedisClient;
+    if (!redis)
+        return null;
+    const data = await redis.get(getCacheKey(target, cacheConfig.keyPrefix));
+    if (!data)
+        return null;
+    return deserializeOptions(data);
+}
+async function invalidateForeignTableCache(target) {
+    const opts = getForeignTableOptions(target);
+    if (!opts)
+        return;
+    const cacheConfig = opts.cache;
+    if (!cacheConfig?.redis)
+        return;
+    const redis = globalRedisClient;
+    if (!redis)
+        return;
+    await redis.del(getCacheKey(target, cacheConfig.keyPrefix));
+}
+async function warmupForeignTableCache(target, prorm) {
+    await cacheForeignTableOptions(target);
+}
+exports.ForeignTableRegistry = {
+    getOptions(target) {
+        return getForeignTableOptions(target);
+    },
+    isForeignTable(target) {
+        return isForeignTable(target);
+    },
+    getSQL(target) {
+        const opts = getForeignTableOptions(target);
+        if (!opts)
+            throw new Error('[ORM] Class ' + target.name + ' does not have a @ForeignTable decorator.');
+        if (!opts.server)
+            throw new Error('[ORM] @ForeignTable requires a server option.');
+        const schema = opts.schema ?? 'public';
+        const tableName = target.name;
+        const columns = opts.columns ?? {};
+        const columnDefs = Object.entries(columns)
+            .map(([name, col]) => {
+            let def = name + ' ' + col.type;
+            if (col.options)
+                def += ' ' + col.options;
+            return def;
+        })
+            .join(',\n  ');
+        if (!columnDefs)
+            throw new Error('[ORM] @ForeignTable requires columns option.');
+        let sql = `CREATE FOREIGN TABLE "${tableName}" (\n  ${columnDefs}\n) SERVER "${opts.server}"`;
+        if (opts.foreignSchema) {
+            sql += `\n  OPTIONS (schema '${opts.foreignSchema}')`;
+        }
+        if (opts.ifNotExists) {
+            sql = sql.replace('CREATE FOREIGN TABLE', 'CREATE FOREIGN TABLE IF NOT EXISTS');
+        }
+        return sql;
+    },
+};

package/dist/decorators/generated.js

@@ -0,0 +1,274 @@
+"use strict";
+/**
+ * Generated Column decorators for the ORM.
+ *
+ * Supports database-level computed columns:
+ * - VIRTUAL: Computed on read, not stored in DB
+ * - STORED: Computed on write, physically stored in DB
+ * - IDENTITY: Auto-increment primary key configuration
+ *
+ * Usage:
+ *
+ *   // Virtual computed column (default)
+ *   @Generated()
+ *   get fullName() {
+ *     return `${this.firstName} ${this.lastName}`;
+ *   }
+ *
+ *   // Stored computed column
+ *   @Generated('stored')
+ *   get total() {
+ *     return this.price * this.quantity;
+ *   }
+ *
+ *   // With custom expression
+ *   @Generated({
+ *     as: 'CONCAT(first_name, " ", last_name)',
+ *     type: 'varchar(255)',
+ *     stored: true
+ *   })
+ *   fullName: string;
+ *
+ *   // Identity/Auto-increment configuration
+ *   @Generated({
+ *     identity: true,
+ *     start: 1,
+ *     increment: 1,
+ *     cache: 1000
+ *   })
+ *   id: number;
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Generated = Generated;
+exports.Identity = Identity;
+exports.getGeneratedMetadata = getGeneratedMetadata;
+exports.getIdentityMetadata = getIdentityMetadata;
+exports.getAllGeneratedMetadata = getAllGeneratedMetadata;
+exports.getAllIdentityMetadata = getAllIdentityMetadata;
+exports.isGeneratedColumn = isGeneratedColumn;
+exports.isIdentityColumn = isIdentityColumn;
+exports.buildGeneratedSQL = buildGeneratedSQL;
+exports.isStored = isStored;
+require("reflect-metadata");
+// ==================== Metadata Key ====================
+/**
+ * Symbol for storing generated column metadata
+ */
+const GENERATED_METADATA_KEY = Symbol('prorm:generated');
+/**
+ * Symbol for storing identity/auto-increment metadata
+ */
+const IDENTITY_METADATA_KEY = Symbol('prorm:identity');
+// ==================== Decorators ====================
+/**
+ * Decorator for generated/computed columns.
+ *
+ * Usage with getter (for computed properties):
+ *
+ *   class User extends Model {
+ *     @Generated()
+ *     get fullName() {
+ *       return `${this.firstName} ${this.lastName}`;
+ *     }
+ *   }
+ *
+ * Usage with options:
+ *
+ *   @Generated({
+ *     as: 'CONCAT(first_name, " ", last_name)',
+ *     type: 'varchar(255)',
+ *     stored: true
+ *   })
+ *   fullName: string;
+ *
+ * @param options - Generated column options or just storage type
+ */
+function Generated(options) {
+    return function (target, propertyKey) {
+        const opts = normalizeOptions(options);
+        // Store metadata
+        const metadata = {
+            propertyName: String(propertyKey),
+            options: opts,
+        };
+        Reflect.defineMetadata(GENERATED_METADATA_KEY, metadata, target, String(propertyKey));
+        // Also handle identity separately if enabled
+        if (opts.identity) {
+            Reflect.defineMetadata(IDENTITY_METADATA_KEY, { propertyName: String(propertyKey), options: opts }, target, String(propertyKey));
+        }
+    };
+}
+/**
+ * Decorator specifically for identity/auto-increment columns.
+ *
+ * Usage:
+ *
+ *   @Generated({
+ *     identity: true,
+ *     start: 1,
+ *     increment: 1,
+ *     cache: 1000
+ *   })
+ *   id: number;
+ *
+ * @param options - Identity configuration options
+ */
+function Identity(options) {
+    return function (target, propertyKey) {
+        const opts = {
+            ...options,
+            identity: true,
+        };
+        Reflect.defineMetadata(IDENTITY_METADATA_KEY, { propertyName: String(propertyKey), options: opts }, target, String(propertyKey));
+    };
+}
+// ==================== Helper Functions ====================
+/**
+ * Normalize options from various input formats
+ */
+function normalizeOptions(options) {
+    if (!options) {
+        // `stored` is left undefined here rather than defaulting to `false`,
+        // because the correct default depends on the target dialect (see
+        // `isStored`) and the dialect isn't known at decoration time.
+        return {};
+    }
+    if (typeof options === 'string') {
+        return { stored: options === 'stored' };
+    }
+    return options;
+}
+/**
+ * Get generated column metadata for a property.
+ *
+ * @param target - The target class or prototype
+ * @param propertyKey - The property name
+ * @returns The generated metadata or undefined
+ */
+function getGeneratedMetadata(target, propertyKey) {
+    return Reflect.getMetadata(GENERATED_METADATA_KEY, target, propertyKey);
+}
+/**
+ * Get identity metadata for a property.
+ *
+ * @param target - The target class or prototype
+ * @param propertyKey - The property name
+ * @returns The identity metadata or undefined
+ */
+function getIdentityMetadata(target, propertyKey) {
+    return Reflect.getMetadata(IDENTITY_METADATA_KEY, target, propertyKey);
+}
+/**
+ * Get all generated column metadata for a class.
+ *
+ * @param target - The target class or prototype
+ * @returns Map of property names to their generated metadata
+ */
+function getAllGeneratedMetadata(target) {
+    const result = new Map();
+    // Get all own property keys
+    const keys = Object.getOwnPropertyNames(target);
+    for (const key of keys) {
+        const metadata = getGeneratedMetadata(target, key);
+        if (metadata) {
+            result.set(key, metadata);
+        }
+    }
+    // Also check prototype chain for inherited metadata
+    const proto = Object.getPrototypeOf(target);
+    if (proto && Object.getPrototypeOf(proto) !== null) {
+        const inherited = getAllGeneratedMetadata(proto);
+        for (const [key, value] of inherited) {
+            if (!result.has(key)) {
+                result.set(key, value);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Get all identity metadata for a class.
+ *
+ * @param target - The target class or prototype
+ * @returns Map of property names to their identity metadata
+ */
+function getAllIdentityMetadata(target) {
+    const result = new Map();
+    const keys = Object.getOwnPropertyNames(target);
+    for (const key of keys) {
+        const metadata = getIdentityMetadata(target, key);
+        if (metadata) {
+            result.set(key, metadata);
+        }
+    }
+    const proto = Object.getPrototypeOf(target);
+    if (proto && Object.getPrototypeOf(proto) !== null) {
+        const inherited = getAllIdentityMetadata(proto);
+        for (const [key, value] of inherited) {
+            if (!result.has(key)) {
+                result.set(key, value);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Check if a property is a generated column.
+ *
+ * @param target - The target class or prototype
+ * @param propertyKey - The property name
+ * @returns True if the property is generated
+ */
+function isGeneratedColumn(target, propertyKey) {
+    return !!getGeneratedMetadata(target, propertyKey);
+}
+/**
+ * Check if a property is an identity/auto-increment column.
+ *
+ * @param target - The target class or prototype
+ * @param propertyKey - The property name
+ * @returns True if the property is an identity column
+ */
+function isIdentityColumn(target, propertyKey) {
+    const metadata = getIdentityMetadata(target, propertyKey);
+    return !!metadata?.options.identity;
+}
+/**
+ * Build the SQL expression for a generated column.
+ *
+ * @param options - The generated column options
+ * @returns The SQL expression string
+ */
+function buildGeneratedSQL(options) {
+    if (options.as) {
+        return options.as;
+    }
+    // If no custom expression, return empty
+    return '';
+}
+/**
+ * Check if generated column is stored (persisted) or virtual.
+ *
+ * When `options.stored` is explicitly set, that value is used as-is.
+ * When it is left unspecified, the default depends on the target dialect:
+ * - PostgreSQL (before v18) only supports `STORED` generated columns —
+ *   `VIRTUAL` is not a valid option, so it defaults to `true` (stored).
+ * - MySQL/MariaDB support both `VIRTUAL` and `STORED`, and default to
+ *   `VIRTUAL` (the lighter-weight option), so this defaults to `false`.
+ * - Other dialects (sqlite, mssql, oracle) also default to `false`
+ *   (virtual/computed, not persisted), matching their typical defaults.
+ *
+ * @param options - The generated column options
+ * @param dialect - The target SQL dialect (defaults to 'mysql' for backwards compatibility)
+ * @returns True if stored, false if virtual
+ */
+function isStored(options, dialect = 'mysql') {
+    if (options.stored !== undefined) {
+        return options.stored;
+    }
+    // PostgreSQL doesn't support VIRTUAL generated columns before v18 —
+    // fall back to STORED, the only option it actually supports.
+    return dialect === 'postgres';
+}
+// ==================== Exports ====================
+// Types are exported inline with the interfaces/classes above

package/dist/decorators/has-many.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * HasMany decorator for the ORM.
+ *
+ * Defines a one-to-many relationship between models.
+ *
+ * Usage:
+ *
+ *   @HasMany(() => Post)
+ *   posts: Post[];
+ *
+ *   @HasMany(() => Post, { as: 'articles' })
+ *   articles: Post[];
+ *
+ *   // With options
+ *   @HasMany(() => Order, {
+ *     foreignKey: { name: 'user_id', allowNull: false },
+ *     onDelete: 'CASCADE',
+ *     through: 'user_orders'  // For belongsToMany
+ *   })
+ *   orders: Order[];
+ *
+ *   // Self-referential
+ *   @HasMany(() => Category, { as: 'children', foreignKey: 'parent_id' })
+ *   children: Category[];
+ *
+ *   // Nested hasMany with scope
+ *   @HasMany(() => Comment, {
+ *     as: 'replies',
+ *     foreignKey: 'parent_id',
+ *     scope: { deleted: false }
+ *   })
+ *   replies: Comment[];
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHasMany = getHasMany;
+exports.getAllHasMany = getAllHasMany;
+exports.HasMany = HasMany;
+exports.processHasManyDecorators = processHasManyDecorators;
+// ==================== Metadata Storage ====================
+const HAS_MANY_KEY = '__orm_has_many__';
+/**
+ * Get all @HasMany annotations attached to a model constructor.
+ */
+function getHasMany(target) {
+    return target[HAS_MANY_KEY] || [];
+}
+/**
+ * Get all hasMany associations including inherited ones.
+ */
+function getAllHasMany(target) {
+    const associations = [];
+    let current = target;
+    while (current && current.prototype) {
+        const meta = getHasMany(current);
+        associations.push(...meta);
+        current = Object.getPrototypeOf(current);
+        if (current === Object.prototype)
+            break;
+    }
+    return associations;
+}
+// ==================== Decorator ====================
+/**
+ * Define a one-to-many relationship.
+ *
+ * This decorator stores metadata on the model class that can be used
+ * by the ORM to establish the association at model initialization time.
+ *
+ * @param target - A function that returns the target model class
+ * @param options - Optional configuration for the association
+ */
+function HasMany(target, options = {}) {
+    return function (prototype, propertyKey) {
+        const ModelClass = prototype.constructor;
+        if (!ModelClass[HAS_MANY_KEY]) {
+            ModelClass[HAS_MANY_KEY] = [];
+        }
+        ModelClass[HAS_MANY_KEY].push({
+            target,
+            options: {
+                as: options.as || propertyKey.toString(),
+                foreignKey: options.foreignKey,
+                constraints: options.constraints,
+                onDelete: options.onDelete,
+                onUpdate: options.onUpdate,
+                targetKey: options.targetKey,
+                sourceKey: options.sourceKey,
+                scope: options.scope,
+                through: options.through,
+                inverse: options.inverse,
+            },
+        });
+    };
+}
+/**
+ * Process @HasMany decorators and create association configuration.
+ *
+ * Call this to get the raw association definitions from decorators.
+ *
+ * @param ModelClass - The model class with @HasMany decorators
+ * @returns Array of association configurations
+ */
+function processHasManyDecorators(ModelClass) {
+    const decorators = getAllHasMany(ModelClass);
+    return decorators.map(({ target, options }) => {
+        const targetModel = target();
+        const foreignKey = typeof options.foreignKey === 'string'
+            ? options.foreignKey
+            : options.foreignKey?.name
+                ? options.foreignKey.name
+                : `${ModelClass.name}Id`;
+        return {
+            source: ModelClass,
+            target: targetModel,
+            foreignKey,
+            as: options.as || '',
+            options,
+        };
+    });
+}
+exports.default = {
+    HasMany,
+    getHasMany,
+    getAllHasMany,
+    processHasManyDecorators,
+};

package/dist/decorators/has-one.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * HasOne decorator for the ORM.
+ *
+ * Defines a one-to-one relationship between models.
+ *
+ * Usage:
+ *
+ *   @HasOne(() => Profile)
+ *   profile: Profile;
+ *
+ *   @HasOne(() => Profile, { as: 'userProfile' })
+ *   userProfile: Profile;
+ *
+ *   // With options
+ *   @HasOne(() => Profile, {
+ *     foreignKey: { name: 'user_id', allowNull: false },
+ *     onDelete: 'CASCADE'
+ *   })
+ *   profile: Profile;
+ *
+ *   // Self-referential
+ *   @HasOne(() => User, { as: 'manager', foreignKey: 'manager_id' })
+ *   manager: User;
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHasOne = getHasOne;
+exports.getAllHasOne = getAllHasOne;
+exports.HasOne = HasOne;
+exports.processHasOneDecorators = processHasOneDecorators;
+// ==================== Metadata Storage ====================
+const HAS_ONE_KEY = '__orm_has_one__';
+/**
+ * Get all @HasOne annotations attached to a model constructor.
+ */
+function getHasOne(target) {
+    return target[HAS_ONE_KEY] || [];
+}
+/**
+ * Get all hasOne associations including inherited ones.
+ */
+function getAllHasOne(target) {
+    const associations = [];
+    let current = target;
+    while (current && current.prototype) {
+        const meta = getHasOne(current);
+        associations.push(...meta);
+        current = Object.getPrototypeOf(current);
+        if (current === Object.prototype)
+            break;
+    }
+    return associations;
+}
+// ==================== Decorator ====================
+/**
+ * Define a one-to-one relationship.
+ *
+ * This decorator stores metadata on the model class that can be used
+ * by the ORM to establish the association at model initialization time.
+ *
+ * @param target - A function that returns the target model class
+ * @param options - Optional configuration for the association
+ */
+function HasOne(target, options = {}) {
+    return function (prototype, propertyKey) {
+        const ModelClass = prototype.constructor;
+        if (!ModelClass[HAS_ONE_KEY]) {
+            ModelClass[HAS_ONE_KEY] = [];
+        }
+        ModelClass[HAS_ONE_KEY].push({
+            target,
+            options: {
+                as: options.as || propertyKey.toString(),
+                foreignKey: options.foreignKey,
+                constraints: options.constraints,
+                onDelete: options.onDelete,
+                onUpdate: options.onUpdate,
+                targetKey: options.targetKey,
+                sourceKey: options.sourceKey,
+                inverse: options.inverse,
+            },
+        });
+    };
+}
+/**
+ * Process @HasOne decorators and create association configuration.
+ *
+ * Call this to get the raw association definitions from decorators.
+ *
+ * @param ModelClass - The model class with @HasOne decorators
+ * @returns Array of association configurations
+ */
+function processHasOneDecorators(ModelClass) {
+    const decorators = getAllHasOne(ModelClass);
+    return decorators.map(({ target, options }) => {
+        const targetModel = target();
+        const foreignKey = typeof options.foreignKey === 'string'
+            ? options.foreignKey
+            : options.foreignKey?.name
+                ? options.foreignKey.name
+                : `${ModelClass.name}Id`;
+        return {
+            source: ModelClass,
+            target: targetModel,
+            foreignKey,
+            as: options.as || '',
+            options,
+        };
+    });
+}
+exports.default = {
+    HasOne,
+    getHasOne,
+    getAllHasOne,
+    processHasOneDecorators,
+};