ts-prorm-orm 1.1.0 → 1.2.0

package/dist/models/methods.d.ts

@@ -0,0 +1,419 @@
+/**
+ * Custom Methods Helpers for Models
+ *
+ * This module provides utilities for adding custom class and instance methods
+ * to Prorm-like models.
+ */
+import { ModelStatic, ModelInstance } from '../types';
+/**
+ * Add custom class methods to a model
+ * Use this to add static methods to a model (e.g., User.findByEmail)
+ *
+ * @example
+ * ```typescript
+ * addClassMethods(User, {
+ *   findByEmail: async function(email) {
+ *     return this.findOne({ where: { email } });
+ *   },
+ *   findByRole: function(role) {
+ *     return this.findAll({ where: { role } });
+ *   }
+ * });
+ * ```
+ *
+ * @param model - The model static to add methods to
+ * @param methods - Object containing method names and their implementations
+ */
+export declare function addClassMethods<T extends ModelStatic<any>>(model: T, methods: Record<string, Function>): void;
+/**
+ * Add custom instance methods to a model
+ * Use this to add methods that will be available on model instances (e.g., user.getFullName())
+ *
+ * @example
+ * ```typescript
+ * addInstanceMethods(User, {
+ *   getFullName: function() {
+ *     return `${this.firstName} ${this.lastName}`;
+ *   },
+ *   isActive: function() {
+ *     return this.status === 'active';
+ *   }
+ * });
+ * ```
+ *
+ * @param model - The model static to add methods to
+ * @param methods - Object containing method names and their implementations
+ */
+export declare function addInstanceMethods<T extends ModelStatic<any>>(model: T, methods: Record<string, Function>): void;
+/**
+ * Define custom methods when creating a model using define()
+ * This is the preferred way to add custom methods during model definition
+ *
+ * @example
+ * ```typescript
+ * const User = prorm.define('User', {
+ *   firstName: Prorm.STRING,
+ *   lastName: Prorm.STRING,
+ *   email: Prorm.STRING
+ * }, {
+ *   classMethods: {
+ *     findByEmail: async function(email) {
+ *       return this.findOne({ where: { email } });
+ *     }
+ *   },
+ *   instanceMethods: {
+ *     getFullName: function() {
+ *       return `${this.firstName} ${this.lastName}`;
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export interface ModelWithMethods<T = any> extends ModelStatic<ModelInstance<T>> {
+    findByEmail?: (email: string) => Promise<ModelInstance<T> | null>;
+    findByRole?: (role: string) => Promise<ModelInstance<T>[]>;
+    [key: string]: any;
+}
+export interface InstanceWithMethods<T = any> extends ModelInstance<T> {
+    getFullName?: () => string;
+    isActive?: () => boolean;
+    [key: string]: any;
+}
+/**
+ * Helper to extend a model with additional methods after definition
+ * Useful for adding methods to models defined elsewhere
+ *
+ * @example
+ * ```typescript
+ * // Extend User model with custom methods
+ * extendModel(User, {
+ *   classMethods: {
+ *     findActive: function() {
+ *       return this.findAll({ where: { status: 'active' } });
+ *     }
+ *   },
+ *   instanceMethods: {
+ *     getDisplayName: function() {
+ *       return this.name || this.email;
+ *     }
+ *   }
+ * });
+ * ```
+ *
+ * @param model - The model to extend
+ * @param options - Object containing classMethods and/or instanceMethods
+ */
+export declare function extendModel<T extends ModelStatic<any>>(model: T, options: {
+    classMethods?: Record<string, Function>;
+    instanceMethods?: Record<string, Function>;
+}): void;
+/**
+ * Common instance methods that can be added to any model
+ */
+export declare const commonInstanceMethods: {
+    /**
+     * Get a single attribute value
+     * @example
+     * ```typescript
+     * const name = user.get('firstName');
+     * ```
+     */
+    get(key: string): any;
+    /**
+     * Set a single attribute value
+     * @example
+     * ```typescript
+     * user.set('firstName', 'John');
+     * ```
+     */
+    set(key: string, value: any): void;
+    /**
+     * Get raw data value (bypasses getters)
+     * @example
+     * ```typescript
+     * const value = user.getDataValue('firstName');
+     * ```
+     */
+    getDataValue(key: string): any;
+    /**
+     * Set raw data value (bypasses setters)
+     * @example
+     * ```typescript
+     * user.setDataValue('firstName', 'John');
+     * ```
+     */
+    setDataValue(key: string, value: any): void;
+    /**
+     * Check if record is new (not saved to database)
+     * @example
+     * ```typescript
+     * if (user.isNewRecord) {
+     *   console.log('New user!');
+     * }
+     * ```
+     */
+    isNewRecord(): boolean;
+    /**
+     * Convert instance to JSON
+     * @example
+     * ```typescript
+     * const json = user.toJSON();
+     * ```
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * Check if a specific field has changed
+     * @example
+     * ```typescript
+     * if (user.changed('email')) {
+     *   console.log('Email was changed');
+     * }
+     * ```
+     */
+    changed(key?: string): boolean | string[];
+    /**
+     * Get previous value of a field
+     * @example
+     * ```typescript
+     * const oldEmail = user.previous('email');
+     * ```
+     */
+    previous(key?: string): any;
+};
+/**
+ * Common class methods that can be added to any model
+ */
+export declare const commonClassMethods: {
+    /**
+     * Find a record or create it if not found
+     * @example
+     * ```typescript
+     * const [user, created] = await User.findOrCreate({
+     *   where: { email: 'john@example.com' },
+     *   defaults: { name: 'John' }
+     * });
+     * ```
+     */
+    findOrCreate<T extends ModelStatic<any>>(this: T, options: {
+        where: Record<string, any>;
+        defaults?: Record<string, any>;
+    }): Promise<[ModelInstance<any>, boolean]>;
+    /**
+     * Find a record or build (but not save) it if not found
+     * @example
+     * ```typescript
+     * const [user, built] = await User.findOrBuild({
+     *   where: { email: 'john@example.com' },
+     *   defaults: { name: 'John' }
+     * });
+     * if (built) {
+     *   await user.save();
+     * }
+     * ```
+     */
+    findOrBuild<T extends ModelStatic<any>>(this: T, options: {
+        where: Record<string, any>;
+        defaults?: Record<string, any>;
+    }): Promise<[ModelInstance<any>, boolean]>;
+    /**
+     * Insert or update a record
+     * @example
+     * ```typescript
+     * const [user, isNew] = await User.upsert({
+     *   id: 1,
+     *   name: 'John',
+     *   email: 'john@example.com'
+     * });
+     * ```
+     */
+    upsert<T extends ModelStatic<any>>(this: T, values: Record<string, any>, _options?: {
+        returning?: boolean;
+    }): Promise<[ModelInstance<any>, boolean]>;
+    /**
+     * Find a record by where conditions, or create it with upsert semantics
+     * Similar to findOrCreate but uses upsert for the create path
+     * @example
+     * ```typescript
+     * const [user, created] = await User.upsertOrCreate({
+     *   where: { email: 'john@example.com' },
+     *   defaults: { name: 'John' },
+     *   updateValues: { name: 'John Updated' }
+     * });
+     * ```
+     */
+    upsertOrCreate<T extends ModelStatic<any>>(this: T, options: {
+        where: Record<string, any>;
+        defaults?: Record<string, any>;
+        updateValues?: Record<string, any>;
+    }): Promise<[ModelInstance<any>, boolean]>;
+    /**
+     * Bulk upsert - upsert multiple records at once
+     * @example
+     * ```typescript
+     * const results = await User.bulkUpsert([
+     *   { id: 1, name: 'John' },
+     *   { id: 2, name: 'Jane' },
+     *   { name: 'New User' }
+     * ], { conflictKeys: ['email'], updateKeys: ['name'] });
+     * ```
+     */
+    bulkUpsert<T extends ModelStatic<any>>(this: T, records: Record<string, any>[], options?: {
+        conflictKeys?: string[];
+        updateKeys?: string[];
+    }): Promise<number>;
+};
+declare const _default: {
+    addClassMethods: typeof addClassMethods;
+    addInstanceMethods: typeof addInstanceMethods;
+    extendModel: typeof extendModel;
+    commonInstanceMethods: {
+        /**
+         * Get a single attribute value
+         * @example
+         * ```typescript
+         * const name = user.get('firstName');
+         * ```
+         */
+        get(key: string): any;
+        /**
+         * Set a single attribute value
+         * @example
+         * ```typescript
+         * user.set('firstName', 'John');
+         * ```
+         */
+        set(key: string, value: any): void;
+        /**
+         * Get raw data value (bypasses getters)
+         * @example
+         * ```typescript
+         * const value = user.getDataValue('firstName');
+         * ```
+         */
+        getDataValue(key: string): any;
+        /**
+         * Set raw data value (bypasses setters)
+         * @example
+         * ```typescript
+         * user.setDataValue('firstName', 'John');
+         * ```
+         */
+        setDataValue(key: string, value: any): void;
+        /**
+         * Check if record is new (not saved to database)
+         * @example
+         * ```typescript
+         * if (user.isNewRecord) {
+         *   console.log('New user!');
+         * }
+         * ```
+         */
+        isNewRecord(): boolean;
+        /**
+         * Convert instance to JSON
+         * @example
+         * ```typescript
+         * const json = user.toJSON();
+         * ```
+         */
+        toJSON(): Record<string, any>;
+        /**
+         * Check if a specific field has changed
+         * @example
+         * ```typescript
+         * if (user.changed('email')) {
+         *   console.log('Email was changed');
+         * }
+         * ```
+         */
+        changed(key?: string): boolean | string[];
+        /**
+         * Get previous value of a field
+         * @example
+         * ```typescript
+         * const oldEmail = user.previous('email');
+         * ```
+         */
+        previous(key?: string): any;
+    };
+    commonClassMethods: {
+        /**
+         * Find a record or create it if not found
+         * @example
+         * ```typescript
+         * const [user, created] = await User.findOrCreate({
+         *   where: { email: 'john@example.com' },
+         *   defaults: { name: 'John' }
+         * });
+         * ```
+         */
+        findOrCreate<T extends ModelStatic<any>>(this: T, options: {
+            where: Record<string, any>;
+            defaults?: Record<string, any>;
+        }): Promise<[ModelInstance<any>, boolean]>;
+        /**
+         * Find a record or build (but not save) it if not found
+         * @example
+         * ```typescript
+         * const [user, built] = await User.findOrBuild({
+         *   where: { email: 'john@example.com' },
+         *   defaults: { name: 'John' }
+         * });
+         * if (built) {
+         *   await user.save();
+         * }
+         * ```
+         */
+        findOrBuild<T extends ModelStatic<any>>(this: T, options: {
+            where: Record<string, any>;
+            defaults?: Record<string, any>;
+        }): Promise<[ModelInstance<any>, boolean]>;
+        /**
+         * Insert or update a record
+         * @example
+         * ```typescript
+         * const [user, isNew] = await User.upsert({
+         *   id: 1,
+         *   name: 'John',
+         *   email: 'john@example.com'
+         * });
+         * ```
+         */
+        upsert<T extends ModelStatic<any>>(this: T, values: Record<string, any>, _options?: {
+            returning?: boolean;
+        }): Promise<[ModelInstance<any>, boolean]>;
+        /**
+         * Find a record by where conditions, or create it with upsert semantics
+         * Similar to findOrCreate but uses upsert for the create path
+         * @example
+         * ```typescript
+         * const [user, created] = await User.upsertOrCreate({
+         *   where: { email: 'john@example.com' },
+         *   defaults: { name: 'John' },
+         *   updateValues: { name: 'John Updated' }
+         * });
+         * ```
+         */
+        upsertOrCreate<T extends ModelStatic<any>>(this: T, options: {
+            where: Record<string, any>;
+            defaults?: Record<string, any>;
+            updateValues?: Record<string, any>;
+        }): Promise<[ModelInstance<any>, boolean]>;
+        /**
+         * Bulk upsert - upsert multiple records at once
+         * @example
+         * ```typescript
+         * const results = await User.bulkUpsert([
+         *   { id: 1, name: 'John' },
+         *   { id: 2, name: 'Jane' },
+         *   { name: 'New User' }
+         * ], { conflictKeys: ['email'], updateKeys: ['name'] });
+         * ```
+         */
+        bulkUpsert<T extends ModelStatic<any>>(this: T, records: Record<string, any>[], options?: {
+            conflictKeys?: string[];
+            updateKeys?: string[];
+        }): Promise<number>;
+    };
+};
+export default _default;

package/dist/models/model-manager.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Model Manager Module
+ * Manages model registry and tracking all defined models
+ */
+import { ModelStatic, Model, AttributeOptions, ModelOptions } from '../types';
+/**
+ * Model definition entry
+ */
+export interface ModelDefinition {
+    name: string;
+    attributes: Record<string, AttributeOptions>;
+    options: ModelOptions;
+}
+/**
+ * ModelManager class to track all models
+ */
+export declare class ModelManager {
+    private models;
+    private modelDefinitions;
+    /**
+     * Get a model by name
+     * @param name - Model name
+     */
+    getModel<T extends Model = any>(name: string): ModelStatic<T> | undefined;
+    /**
+     * Set a model
+     * @param name - Model name
+     * @param model - Model static
+     */
+    setModel<T extends Model = any>(name: string, model: ModelStatic<T>): void;
+    /**
+     * Check if a model exists
+     * @param name - Model name
+     */
+    hasModel(name: string): boolean;
+    /**
+     * Remove a model by name
+     * @param name - Model name
+     */
+    removeModel(name: string): boolean;
+    /**
+     * Get all registered models
+     * @returns Map of model name to ModelStatic
+     */
+    getModels(): Map<string, ModelStatic<any>>;
+    /**
+     * Get all model names
+     * @returns Array of model names
+     */
+    getModelNames(): string[];
+    /**
+     * Store a model definition
+     * @param name - Model name
+     * @param attributes - Model attributes
+     * @param options - Model options
+     */
+    addModelDefinition(name: string, attributes: Record<string, AttributeOptions>, options: ModelOptions): void;
+    /**
+     * Get a model definition
+     * @param name - Model name
+     */
+    getModelDefinition(name: string): ModelDefinition | undefined;
+    /**
+     * Get all model definitions
+     */
+    getAllModelDefinitions(): Map<string, ModelDefinition>;
+    /**
+     * Clear all models
+     */
+    clear(): void;
+    /**
+     * Get the count of registered models
+     */
+    getModelCount(): number;
+}
+export default ModelManager;