ts-prorm-orm 1.1.0 → 1.2.0

package/dist/models/decorators.d.ts

@@ -0,0 +1,328 @@
+/**
+ * Model Decorators for TypeScript
+ *
+ * Provides decorators for defining models:
+ * - @Table - Configure table options
+ * - @Attribute - Define a column attribute
+ * - @PrimaryKey - Mark as primary key
+ * - @AutoIncrement - Enable auto-increment
+ * - @NotNull - Add NOT NULL constraint
+ * - @Default - Set default value
+ * - @Unique - Add UNIQUE constraint
+ * - @Comment - Add column comment
+ */
+import type { IndexOptions } from '../dialects/dialect';
+/**
+ * @example
+ * ```typescript
+ * import { Model, DataTypes, InferAttributes, InferCreationAttributes } from 'orm';
+ * import { Table, Attribute, PrimaryKey, AutoIncrement, NotNull, Default } from 'orm/decorators';
+ *
+ * @Table({ tableName: 'users', timestamps: true })
+ * export class User extends Model<InferAttributes<User>, InferCreationAttributes<User>> {
+ *   @Attribute(DataTypes.INTEGER)
+ *   @PrimaryKey
+ *   @AutoIncrement
+ *   declare id: number;
+ *
+ *   @Attribute(DataTypes.STRING)
+ *   @NotNull
+ *   declare name: string;
+ *
+ *   @Attribute(DataTypes.DATE)
+ *   @Default(DataTypes.NOW)
+ *   declare createdAt: Date;
+ * }
+ * ```
+ */
+import { DataType } from './data-types';
+interface ModelMetadata {
+    tableName?: string;
+    schema?: string;
+    schemaDelimiter?: string;
+    modelName?: string;
+    timestamps?: boolean;
+    createdAt?: string | false;
+    updatedAt?: string | false;
+    deletedAt?: string | false;
+    underscored?: boolean;
+    freezeTableName?: boolean;
+    hooks?: Record<string, any> | boolean;
+    indexes?: any[];
+    comment?: string;
+    collate?: string;
+    primaryKey?: boolean;
+    paranoid?: boolean;
+    defaultScope?: Record<string, any>;
+    scopes?: Record<string, any>;
+    validate?: Record<string, any>;
+    name?: {
+        singular?: string;
+        plural?: string;
+    };
+    getterMethods?: Record<string, any>;
+    setterMethods?: Record<string, any>;
+    version?: boolean | string;
+}
+/**
+ * Metadata captured for an @HasOne / @HasMany / @BelongsTo / @BelongsToMany
+ * decorator, in the same spirit as AttributeMetadata above.
+ */
+export interface AssociationMetadata {
+    /** Association kind */
+    type: 'hasOne' | 'hasMany' | 'belongsTo' | 'belongsToMany';
+    /** Property the decorator was applied to (e.g. 'profile', 'posts') */
+    propertyKey: string;
+    /** Lazily-resolved target model class (avoids circular import ordering issues) */
+    target: () => any;
+    /** Alias for the association (defaults to the property name) */
+    as: string;
+    /** Foreign key column name */
+    foreignKey?: string;
+    /** Source-side key (used by hasOne/hasMany) */
+    sourceKey?: string;
+    /** Target-side key (used by belongsTo) */
+    targetKey?: string;
+    /** Other key on the join table (used by belongsToMany) */
+    otherKey?: string;
+    /** Through model/table for belongsToMany */
+    through?: any;
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    hooks?: boolean;
+}
+interface AttributeMetadata {
+    fieldName?: string;
+    type: DataType | string;
+    allowNull?: boolean;
+    defaultValue?: any;
+    primaryKey?: boolean;
+    autoIncrement?: boolean;
+    unique?: boolean | string;
+    notNull?: boolean;
+    comment?: string;
+    references?: string;
+    referencesKey?: string;
+    validate?: Record<string, any>;
+}
+/**
+ * Define model options (use on model class)
+ *
+ * @example
+ * @Table({ tableName: 'users', timestamps: true })
+ */
+export declare function Table(options?: TableOptions): ClassDecorator;
+/**
+ * Table options interface
+ */
+export interface TableOptions {
+    /** Table name (defaults to model name) */
+    tableName?: string;
+    /** Schema name */
+    schema?: string;
+    /** Schema delimiter */
+    schemaDelimiter?: string;
+    /** Model name override */
+    modelName?: string;
+    /** Enable timestamps (default: true) */
+    timestamps?: boolean;
+    /** CreatedAt column name (default: 'createdAt') */
+    createdAt?: string | false;
+    /** UpdatedAt column name (default: 'updatedAt') */
+    updatedAt?: string | false;
+    /** DeletedAt column name for paranoid deletes */
+    deletedAt?: string | false;
+    /** Use underscored column names */
+    underscored?: boolean;
+    /** Don't pluralize table name */
+    freezeTableName?: boolean;
+    /** Lifecycle hooks (e.g. beforeCreate, afterCreate) */
+    hooks?: Record<string, (...args: any[]) => any> | boolean;
+    /** Indexes */
+    indexes?: IndexOptions[];
+    /** Table comment */
+    comment?: string;
+    /** Collation (MySQL) */
+    collate?: string;
+    /** Custom primary key */
+    primaryKey?: boolean;
+    /** Enable soft-deletes (paranoid mode). Implied when `deletedAt` is set. */
+    paranoid?: boolean;
+    /** Default scope applied to all queries unless overridden */
+    defaultScope?: Record<string, any>;
+    /** Named scopes available via Model.scope(name) */
+    scopes?: Record<string, any>;
+    /** Model-level validation rules */
+    validate?: Record<string, any>;
+    /** Singular/plural model naming overrides */
+    name?: {
+        singular?: string;
+        plural?: string;
+    };
+    /** Virtual getter methods */
+    getterMethods?: Record<string, (...args: any[]) => any>;
+    /** Virtual setter methods */
+    setterMethods?: Record<string, (...args: any[]) => any>;
+    /** Enable optimistic locking version column */
+    version?: boolean | string;
+}
+export declare function Attribute(type: DataType | string): PropertyDecorator;
+/**
+ * Column decorator - alias for Attribute
+ */
+export declare function Column(type: DataType | string): PropertyDecorator;
+/**
+ * AllowNull decorator - mark attribute as nullable (default)
+ */
+export declare function AllowNull(allowNull?: boolean): PropertyDecorator;
+/**
+ * Mark attribute as primary key
+ *
+ * @example
+ * @Attribute(DataTypes.INTEGER)
+ * @PrimaryKey
+ */
+export declare function PrimaryKey(): PropertyDecorator;
+/**
+ * Enable auto-increment on attribute
+ *
+ * @example
+ * @Attribute(DataTypes.INTEGER)
+ * @AutoIncrement
+ */
+export declare function AutoIncrement(): PropertyDecorator;
+/**
+ * Add NOT NULL constraint
+ *
+ * @example
+ * @Attribute(DataTypes.STRING)
+ * @NotNull
+ */
+export declare function NotNull(): PropertyDecorator;
+/**
+ * Set default value
+ *
+ * @example
+ * @Default('value')
+ * @Default(DataTypes.NOW)
+ * @Default(() => Math.random())
+ */
+export declare function Default(value: any): PropertyDecorator;
+/**
+ * Add UNIQUE constraint
+ *
+ * @example
+ * @Unique
+ * @Unique('unique_name')
+ */
+export declare function Unique(nameOrOptions?: string | boolean): PropertyDecorator;
+/**
+ * Add comment to column
+ *
+ * @example
+ * @Comment('User email address')
+ */
+export declare function Comment(text: string): PropertyDecorator;
+/**
+ * Define a hasOne association
+ *
+ * @example
+ * @HasOne(() => Profile)
+ * declare profile: HasOne<Profile>;
+ */
+export declare function HasOne(targetFn: () => any, options?: HasOneOptions): PropertyDecorator;
+/**
+ * Define a hasMany association
+ *
+ * @example
+ * @HasMany(() => Post)
+ * declare posts: HasMany<Post>;
+ */
+export declare function HasMany(targetFn: () => any, options?: HasManyOptions): PropertyDecorator;
+/**
+ * Define a belongsTo association
+ *
+ * @example
+ * @BelongsTo(() => User)
+ * declare user: BelongsTo<User>;
+ */
+export declare function BelongsTo(targetFn: () => any, options?: BelongsToOptions): PropertyDecorator;
+/**
+ * Define a belongsToMany association
+ *
+ * @example
+ * @BelongsToMany(() => Role, { through: UserRole })
+ * declare roles: BelongsToMany<Role>;
+ */
+export declare function BelongsToMany(targetFn: () => any, options: BelongsToManyOptions): PropertyDecorator;
+export interface HasOneOptions {
+    as?: string;
+    foreignKey?: string;
+    sourceKey?: string;
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    hooks?: boolean;
+}
+export interface HasManyOptions {
+    as?: string;
+    foreignKey?: string;
+    sourceKey?: string;
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    hooks?: boolean;
+}
+export interface BelongsToOptions {
+    as?: string;
+    foreignKey?: string;
+    targetKey?: string;
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    hooks?: boolean;
+}
+export interface BelongsToManyOptions {
+    as?: string;
+    through: any;
+    foreignKey?: string;
+    otherKey?: string;
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    onUpdate?: 'CASCADE' | 'SET NULL' | 'RESTRICT' | 'NO ACTION';
+    hooks?: boolean;
+}
+/**
+ * Get model metadata
+ */
+export declare function getModelMetadata(modelName: string): ModelMetadata | undefined;
+/**
+ * Get attribute metadata for a model
+ */
+export declare function getAttributeMetadata(modelName: string): Map<string, AttributeMetadata> | undefined;
+/**
+ * Get association metadata (from @HasOne/@HasMany/@BelongsTo/@BelongsToMany)
+ * recorded for a model.
+ */
+export declare function getAssociationMetadata(modelName: string): AssociationMetadata[] | undefined;
+/**
+ * Extract all attributes from a model class
+ */
+export declare function getModelAttributes<T = any>(model: new () => T): Record<string, AttributeMetadata>;
+/**
+ * Clear all metadata (useful for testing)
+ */
+export declare function clearMetadata(): void;
+/**
+ * Type helper for hasOne association return
+ */
+export type HasOne<T> = T;
+/**
+ * Type helper for hasMany association return
+ */
+export type HasMany<T> = T[];
+/**
+ * Type helper for belongsTo association return
+ */
+export type BelongsTo<T> = T | null;
+/**
+ * Type helper for belongsToMany association return
+ */
+export type BelongsToMany<T> = T[];
+export {};

package/dist/models/decorators.js

@@ -110,20 +110,49 @@ function Table(options = {}) {
  * @Attribute(DataTypes.STRING)
  * @Attribute(DataTypes.INTEGER)
  */
+/**
+ * Get (creating if needed) the attribute entry for a decorated property.
+ *
+ * Stacked property decorators are applied bottom-up, so a modifier such as
+ * `@PrimaryKey` frequently runs *before* the `@Column` that declares the
+ * attribute. These modifiers previously bailed out when the entry did not exist
+ * yet, and `@Column` then replaced whatever they had set - so the documented
+ * ordering
+ *
+ *     @Column(DataTypes.INTEGER())
+ *     @PrimaryKey()
+ *     @AutoIncrement()
+ *     declare id: number;
+ *
+ * produced a plain nullable INTEGER with no primary key and no auto-increment.
+ * Every decorator now goes through this helper and merges, making the stack
+ * order-independent.
+ */
+function ensureAttr(target, propertyKey) {
+    const modelName = target?.constructor?.name;
+    if (!modelName)
+        return undefined;
+    if (!attributeMetadata.has(modelName)) {
+        attributeMetadata.set(modelName, new Map());
+    }
+    const attrs = attributeMetadata.get(modelName);
+    const fieldName = String(propertyKey);
+    let attr = attrs.get(fieldName);
+    if (!attr) {
+        // Placeholder type; a later @Column/@Attribute overwrites just the type.
+        attr = { type: data_types_1.DataTypes.INTEGER(), allowNull: true };
+        attrs.set(fieldName, attr);
+    }
+    return attr;
+}
 function Attribute(type) {
     return function (target, propertyKey) {
-        const modelName = target.constructor?.name;
-        if (!modelName)
+        const attr = ensureAttr(target, propertyKey);
+        if (!attr)
             return;
-        if (!attributeMetadata.has(modelName)) {
-            attributeMetadata.set(modelName, new Map());
-        }
-        const attrs = attributeMetadata.get(modelName);
-        const fieldName = String(propertyKey);
-        attrs.set(fieldName, {
-            type,
-            allowNull: true,
-        });
+        // Set only the type: modifiers such as @PrimaryKey / @AutoIncrement may
+        // already have run (decorators apply bottom-up) and must not be discarded.
+        attr.type = type;
     };
 }
 /**
@@ -137,17 +166,9 @@ function Column(type) {
  */
 function AllowNull(allowNull = true) {
     return function (target, propertyKey) {
-        const modelName = target.constructor?.name;
-        if (!modelName)
-            return;
-        const attrs = attributeMetadata.get(modelName);
-        if (attrs) {
-            const fieldName = String(propertyKey);
-            const attr = attrs.get(fieldName);
-            if (attr) {
-                attr.allowNull = allowNull;
-            }
-        }
+        const attr = ensureAttr(target, propertyKey);
+        if (attr)
+            attr.allowNull = allowNull;
     };
 }
 /**
@@ -159,17 +180,8 @@ function AllowNull(allowNull = true) {
  */
 function PrimaryKey() {
     return function (target, propertyKey) {
-        const modelName = target.constructor?.name;
-        if (!modelName)
-            return;
-        const attrs = attributeMetadata.get(modelName);
-        if (attrs) {
-            const fieldName = String(propertyKey);
-            let attr = attrs.get(fieldName);
-            if (!attr) {
-                attr = { type: data_types_1.DataTypes.INTEGER() };
-                attrs.set(fieldName, attr);
-            }
+        const attr = ensureAttr(target, propertyKey);
+        if (attr) {
             attr.primaryKey = true;
             attr.allowNull = false;
         }
@@ -184,17 +196,9 @@ function PrimaryKey() {
  */
 function AutoIncrement() {
     return function (target, propertyKey) {
-        const modelName = target.constructor?.name;
-        if (!modelName)
-            return;
-        const attrs = attributeMetadata.get(modelName);
-        if (attrs) {
-            const fieldName = String(propertyKey);
-            const attr = attrs.get(fieldName);
-            if (attr) {
-                attr.autoIncrement = true;
-            }
-        }
+        const attr = ensureAttr(target, propertyKey);
+        if (attr)
+            attr.autoIncrement = true;
     };
 }
 /**
@@ -209,14 +213,10 @@ function NotNull() {
         const modelName = target.constructor?.name;
         if (!modelName)
             return;
-        const attrs = attributeMetadata.get(modelName);
-        if (attrs) {
-            const fieldName = String(propertyKey);
-            const attr = attrs.get(fieldName);
-            if (attr) {
-                attr.notNull = true;
-                attr.allowNull = false;
-            }
+        const attr = ensureAttr(target, propertyKey);
+        if (attr) {
+            attr.notNull = true;
+            attr.allowNull = false;
         }
     };
 }
@@ -230,16 +230,9 @@ function NotNull() {
  */
 function Default(value) {
     return function (target, propertyKey) {
-        const modelName = target.constructor?.name;
-        if (!modelName)
-            return;
-        const attrs = attributeMetadata.get(modelName);
-        if (attrs) {
-            const fieldName = String(propertyKey);
-            const attr = attrs.get(fieldName);
-            if (attr) {
-                attr.defaultValue = value;
-            }
+        const attr = ensureAttr(target, propertyKey);
+        if (attr) {
+            attr.defaultValue = value;
         }
     };
 }
@@ -252,16 +245,9 @@ function Default(value) {
  */
 function Unique(nameOrOptions) {
     return function (target, propertyKey) {
-        const modelName = target.constructor?.name;
-        if (!modelName)
-            return;
-        const attrs = attributeMetadata.get(modelName);
-        if (attrs) {
-            const fieldName = String(propertyKey);
-            const attr = attrs.get(fieldName);
-            if (attr) {
-                attr.unique = typeof nameOrOptions === 'string' ? nameOrOptions : true;
-            }
+        const attr = ensureAttr(target, propertyKey);
+        if (attr) {
+            attr.unique = typeof nameOrOptions === 'string' ? nameOrOptions : true;
         }
     };
 }
@@ -273,16 +259,9 @@ function Unique(nameOrOptions) {
  */
 function Comment(text) {
     return function (target, propertyKey) {
-        const modelName = target.constructor?.name;
-        if (!modelName)
-            return;
-        const attrs = attributeMetadata.get(modelName);
-        if (attrs) {
-            const fieldName = String(propertyKey);
-            const attr = attrs.get(fieldName);
-            if (attr) {
-                attr.comment = text;
-            }
+        const attr = ensureAttr(target, propertyKey);
+        if (attr) {
+            attr.comment = text;
         }
     };
 }

package/dist/models/eager-load.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared eager-loading (`include`) implementation.
+ *
+ * There used to be two separate implementations of this: one inside
+ * `Prorm.define()`'s `findAll` closure (used by models created with
+ * `prorm.define(...)`) and one in `models/model.ts` (`processNestedIncludes`,
+ * used by the class-based `Model` API). Both were live, and they had drifted:
+ * the model.ts copy treated `belongsTo` exactly like `hasMany` - querying the
+ * target table for a foreign key that actually lives on the parent - and
+ * skipped `belongsToMany` entirely with a bare `continue`. Which of the two
+ * bugs you hit depended on which API you had used to define the model.
+ *
+ * Both paths now call `loadIncludes()` below.
+ */
+/** Minimal view of the association records kept in `Prorm.associations`. */
+export interface EagerLoadAssociation {
+    type: 'belongsTo' | 'hasOne' | 'hasMany' | 'belongsToMany';
+    source: any;
+    target: any;
+    foreignKey: string | string[];
+    as?: string;
+    otherKey?: string;
+    through?: string;
+    throughModel?: any;
+    options?: Record<string, any>;
+}
+/** What the loader needs from the owning Prorm instance. */
+export interface EagerLoadContext {
+    /**
+     * All registered associations, in declaration order.
+     *
+     * Must be an array, not a Map iterator: this is rescanned once per include
+     * and again for every nested level, and a single-use iterator would come
+     * back empty after the first scan.
+     */
+    associations: readonly EagerLoadAssociation[];
+    /** Registered models by name, for resolving a `through` given as a string. */
+    models: Record<string, any> | Map<string, any>;
+}
+/** Resolve a model's primary key attribute name, defaulting to `id`. */
+export declare function resolvePrimaryKeyAttr(m: any): string;
+/**
+ * Find the association backing one `include` entry.
+ *
+ * Matching is deliberately strict about aliases. The previous implementation
+ * scanned for any association linking the two models and took the first hit,
+ * with a second pass that also matched the *reverse* direction - so with both
+ * `Post.belongsTo(User, { as: 'author' })` and
+ * `Post.belongsTo(User, { as: 'editor' })` declared, an unaliased
+ * `include: [User]` silently bound to whichever was registered first, and could
+ * bind to an association pointing the other way and then apply the wrong
+ * foreign-key logic to it.
+ */
+export declare function resolveIncludeAssociation(ctx: EagerLoadContext, parentModel: any, parentModelName: string, includeOpt: any): EagerLoadAssociation;
+/**
+ * An include filters its parents when it is `required`, and `required` defaults
+ * to true whenever the include carries its own `where` - the same rule Sequelize
+ * uses, and the one the docs describe as INNER JOIN semantics.
+ */
+export declare function includeFiltersParents(includeOpt: any): boolean;
+/**
+ * Collect the parent-key values that satisfy a filtering (`required`) include.
+ *
+ * This is what gives `required: true` and `include.where` their INNER JOIN
+ * *semantics*: the set of parent keys with a matching child is resolved first,
+ * and the caller adds it to the main query's WHERE so that LIMIT/OFFSET apply
+ * after filtering rather than before. `include` still does not emit a single
+ * JOINed SELECT - associations are fetched with their own queries - but the
+ * rows a filtering include selects are now correct.
+ *
+ * Returns the list of matching parent key values, plus the parent attribute
+ * those values should be compared against.
+ */
+export declare function resolveRequiredIncludeFilter(ctx: EagerLoadContext, parentModel: any, parentModelName: string, rawIncludeOpt: any): Promise<{
+    parentAttr: string;
+    values: any[];
+} | null>;
+/**
+ * Eager-load `includeList` onto `parentRows`, recursing into nested includes.
+ *
+ * Failures are raised as `EagerLoadError` rather than swallowed. They used to be
+ * caught and reported as an empty result, which made a typo'd alias, a missing
+ * foreign key column, an unresolvable through model and a genuinely childless
+ * parent all look identical - and hid most of the bugs this module now fixes.
+ */
+export declare function loadIncludes(ctx: EagerLoadContext, parentRows: any[], parentModel: any, parentModelName: string, includeList: any[]): Promise<void>;