ts-prorm-orm 1.2.3 → 2.1.0

package/dist/models/decorators.d.ts

@@ -106,11 +106,47 @@ interface AttributeMetadata {
     validate?: Record<string, any>;
 }
 /**
- * Define model options (use on model class)
+ * Mark a class as an abstract base model.
  *
- * @example
- * @Table({ tableName: 'users', timestamps: true })
+ * An abstract model gets no table of its own. Its columns, and any
+ * `@PrimaryKey` / `@Default` / validation applied to them, are inherited by the
+ * concrete models that extend it, so shared fields are declared once:
+ *
+ * ```typescript
+ * // This is the base model, which defines the common fields between all comments.
+ * @AbstractModel()
+ * class BaseComment {
+ *   @Column(DataTypes.INTEGER())
+ *   @PrimaryKey()
+ *   @AutoIncrement()
+ *   declare id: number;
+ *
+ *   @Column(DataTypes.TEXT())
+ *   declare body: string;
+ * }
+ *
+ * @Table({ tableName: 'post_comments' })
+ * class PostComment extends BaseComment {
+ *   @Column(DataTypes.INTEGER())
+ *   declare postId: number;
+ * }
+ * ```
+ *
+ * `PostComment` is created with id, body and postId. Passing the abstract class
+ * itself to `addModel()` is an error - there is no table to address.
+ */
+export declare function AbstractModel(options?: TableOptions): ClassDecorator;
+/** True when the class (by name) was declared `@AbstractModel`. */
+export declare function isAbstractModel(nameOrClass: string | Function): boolean;
+/**
+ * Attribute metadata for a model, including everything inherited from abstract
+ * base classes up the prototype chain.
+ *
+ * Metadata is keyed by constructor name, so a subclass would otherwise see only
+ * the columns declared directly on it. Base columns come first, and a subclass
+ * redeclaring a column overrides it.
  */
+export declare function getInheritedAttributeMetadata(modelClass: Function): Map<string, AttributeMetadata>;
 export declare function Table(options?: TableOptions): ClassDecorator;
 /**
  * Table options interface
@@ -179,55 +215,55 @@ export declare function AllowNull(allowNull?: boolean): PropertyDecorator;
  * Mark attribute as primary key
  *
  * @example
- * @Attribute(DataTypes.INTEGER)
- * @PrimaryKey
+ * `@Attribute`(DataTypes.INTEGER)
+ * `@PrimaryKey`
  */
 export declare function PrimaryKey(): PropertyDecorator;
 /**
  * Enable auto-increment on attribute
  *
  * @example
- * @Attribute(DataTypes.INTEGER)
- * @AutoIncrement
+ * `@Attribute`(DataTypes.INTEGER)
+ * `@AutoIncrement`
  */
 export declare function AutoIncrement(): PropertyDecorator;
 /**
  * Add NOT NULL constraint
  *
  * @example
- * @Attribute(DataTypes.STRING)
- * @NotNull
+ * `@Attribute`(DataTypes.STRING)
+ * `@NotNull`
  */
 export declare function NotNull(): PropertyDecorator;
 /**
  * Set default value
  *
  * @example
- * @Default('value')
- * @Default(DataTypes.NOW)
- * @Default(() => Math.random())
+ * `@Default`('value')
+ * `@Default`(DataTypes.NOW)
+ * `@Default`(() => Math.random())
  */
 export declare function Default(value: any): PropertyDecorator;
 /**
  * Add UNIQUE constraint
  *
  * @example
- * @Unique
- * @Unique('unique_name')
+ * `@Unique`
+ * `@Unique`('unique_name')
  */
 export declare function Unique(nameOrOptions?: string | boolean): PropertyDecorator;
 /**
  * Add comment to column
  *
  * @example
- * @Comment('User email address')
+ * `@Comment`('User email address')
  */
 export declare function Comment(text: string): PropertyDecorator;
 /**
  * Define a hasOne association
  *
  * @example
- * @HasOne(() => Profile)
+ * `@HasOne`(() => Profile)
  * declare profile: HasOne<Profile>;
  */
 export declare function HasOne(targetFn: () => any, options?: HasOneOptions): PropertyDecorator;
@@ -235,7 +271,7 @@ export declare function HasOne(targetFn: () => any, options?: HasOneOptions): Pr
  * Define a hasMany association
  *
  * @example
- * @HasMany(() => Post)
+ * `@HasMany`(() => Post)
  * declare posts: HasMany<Post>;
  */
 export declare function HasMany(targetFn: () => any, options?: HasManyOptions): PropertyDecorator;
@@ -243,7 +279,7 @@ export declare function HasMany(targetFn: () => any, options?: HasManyOptions):
  * Define a belongsTo association
  *
  * @example
- * @BelongsTo(() => User)
+ * `@BelongsTo`(() => User)
  * declare user: BelongsTo<User>;
  */
 export declare function BelongsTo(targetFn: () => any, options?: BelongsToOptions): PropertyDecorator;
@@ -251,7 +287,7 @@ export declare function BelongsTo(targetFn: () => any, options?: BelongsToOption
  * Define a belongsToMany association
  *
  * @example
- * @BelongsToMany(() => Role, { through: UserRole })
+ * `@BelongsToMany`(() => Role, { through: UserRole })
  * declare roles: BelongsToMany<Role>;
  */
 export declare function BelongsToMany(targetFn: () => any, options: BelongsToManyOptions): PropertyDecorator;

package/dist/models/decorators.js

@@ -13,6 +13,9 @@
  * - @Comment - Add column comment
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractModel = AbstractModel;
+exports.isAbstractModel = isAbstractModel;
+exports.getInheritedAttributeMetadata = getInheritedAttributeMetadata;
 exports.Table = Table;
 exports.Attribute = Attribute;
 exports.Column = Column;
@@ -68,8 +71,79 @@ const associationMetadata = new Map();
  * Define model options (use on model class)
  *
  * @example
- * @Table({ tableName: 'users', timestamps: true })
+ * `@Table`({ tableName: 'users', timestamps: true })
+ */
+/** Classes marked with `@AbstractModel`, by constructor name. */
+const abstractModels = new Set();
+/**
+ * Mark a class as an abstract base model.
+ *
+ * An abstract model gets no table of its own. Its columns, and any
+ * `@PrimaryKey` / `@Default` / validation applied to them, are inherited by the
+ * concrete models that extend it, so shared fields are declared once:
+ *
+ * ```typescript
+ * // This is the base model, which defines the common fields between all comments.
+ * @AbstractModel()
+ * class BaseComment {
+ *   @Column(DataTypes.INTEGER())
+ *   @PrimaryKey()
+ *   @AutoIncrement()
+ *   declare id: number;
+ *
+ *   @Column(DataTypes.TEXT())
+ *   declare body: string;
+ * }
+ *
+ * @Table({ tableName: 'post_comments' })
+ * class PostComment extends BaseComment {
+ *   @Column(DataTypes.INTEGER())
+ *   declare postId: number;
+ * }
+ * ```
+ *
+ * `PostComment` is created with id, body and postId. Passing the abstract class
+ * itself to `addModel()` is an error - there is no table to address.
  */
+function AbstractModel(options = {}) {
+    return function (target) {
+        abstractModels.add(target.name);
+        // Record the options so subclasses can inherit timestamps/paranoid and the
+        // rest, but never a tableName - each concrete model names its own table.
+        const { tableName: _ignored, ...inheritable } = options;
+        modelMetadata.set(target.name, { ...inheritable });
+        return target;
+    };
+}
+/** True when the class (by name) was declared `@AbstractModel`. */
+function isAbstractModel(nameOrClass) {
+    return abstractModels.has(typeof nameOrClass === 'string' ? nameOrClass : nameOrClass.name);
+}
+/**
+ * Attribute metadata for a model, including everything inherited from abstract
+ * base classes up the prototype chain.
+ *
+ * Metadata is keyed by constructor name, so a subclass would otherwise see only
+ * the columns declared directly on it. Base columns come first, and a subclass
+ * redeclaring a column overrides it.
+ */
+function getInheritedAttributeMetadata(modelClass) {
+    const chain = [];
+    let current = modelClass;
+    while (current && current !== Function.prototype && current.name) {
+        chain.unshift(current);
+        current = Object.getPrototypeOf(current);
+    }
+    const merged = new Map();
+    for (const cls of chain) {
+        const own = attributeMetadata.get(cls.name);
+        if (!own)
+            continue;
+        for (const [field, meta] of own)
+            merged.set(field, meta);
+    }
+    return merged;
+}
 function Table(options = {}) {
     return function (target) {
         const modelName = target.name;
@@ -107,8 +181,8 @@ function Table(options = {}) {
  * Define a model attribute/column
  *
  * @example
- * @Attribute(DataTypes.STRING)
- * @Attribute(DataTypes.INTEGER)
+ * `@Attribute`(DataTypes.STRING)
+ * `@Attribute`(DataTypes.INTEGER)
  */
 /**
  * Get (creating if needed) the attribute entry for a decorated property.
@@ -119,10 +193,12 @@ function Table(options = {}) {
  * yet, and `@Column` then replaced whatever they had set - so the documented
  * ordering
  *
+ * ```ts
  *     @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
@@ -175,8 +251,8 @@ function AllowNull(allowNull = true) {
  * Mark attribute as primary key
  *
  * @example
- * @Attribute(DataTypes.INTEGER)
- * @PrimaryKey
+ * `@Attribute`(DataTypes.INTEGER)
+ * `@PrimaryKey`
  */
 function PrimaryKey() {
     return function (target, propertyKey) {
@@ -191,8 +267,8 @@ function PrimaryKey() {
  * Enable auto-increment on attribute
  *
  * @example
- * @Attribute(DataTypes.INTEGER)
- * @AutoIncrement
+ * `@Attribute`(DataTypes.INTEGER)
+ * `@AutoIncrement`
  */
 function AutoIncrement() {
     return function (target, propertyKey) {
@@ -205,8 +281,8 @@ function AutoIncrement() {
  * Add NOT NULL constraint
  *
  * @example
- * @Attribute(DataTypes.STRING)
- * @NotNull
+ * `@Attribute`(DataTypes.STRING)
+ * `@NotNull`
  */
 function NotNull() {
     return function (target, propertyKey) {
@@ -224,9 +300,9 @@ function NotNull() {
  * Set default value
  *
  * @example
- * @Default('value')
- * @Default(DataTypes.NOW)
- * @Default(() => Math.random())
+ * `@Default`('value')
+ * `@Default`(DataTypes.NOW)
+ * `@Default`(() => Math.random())
  */
 function Default(value) {
     return function (target, propertyKey) {
@@ -240,8 +316,8 @@ function Default(value) {
  * Add UNIQUE constraint
  *
  * @example
- * @Unique
- * @Unique('unique_name')
+ * `@Unique`
+ * `@Unique`('unique_name')
  */
 function Unique(nameOrOptions) {
     return function (target, propertyKey) {
@@ -255,7 +331,7 @@ function Unique(nameOrOptions) {
  * Add comment to column
  *
  * @example
- * @Comment('User email address')
+ * `@Comment`('User email address')
  */
 function Comment(text) {
     return function (target, propertyKey) {
@@ -270,7 +346,7 @@ function Comment(text) {
  * Define a hasOne association
  *
  * @example
- * @HasOne(() => Profile)
+ * `@HasOne`(() => Profile)
  * declare profile: HasOne<Profile>;
  */
 function HasOne(targetFn, options = {}) {
@@ -299,7 +375,7 @@ function HasOne(targetFn, options = {}) {
  * Define a hasMany association
  *
  * @example
- * @HasMany(() => Post)
+ * `@HasMany`(() => Post)
  * declare posts: HasMany<Post>;
  */
 function HasMany(targetFn, options = {}) {
@@ -328,7 +404,7 @@ function HasMany(targetFn, options = {}) {
  * Define a belongsTo association
  *
  * @example
- * @BelongsTo(() => User)
+ * `@BelongsTo`(() => User)
  * declare user: BelongsTo<User>;
  */
 function BelongsTo(targetFn, options = {}) {
@@ -357,7 +433,7 @@ function BelongsTo(targetFn, options = {}) {
  * Define a belongsToMany association
  *
  * @example
- * @BelongsToMany(() => Role, { through: UserRole })
+ * `@BelongsToMany`(() => Role, { through: UserRole })
  * declare roles: BelongsToMany<Role>;
  */
 function BelongsToMany(targetFn, options) {

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

@@ -11,6 +11,16 @@
  * bugs you hit depended on which API you had used to define the model.
  *
  * Both paths now call `loadIncludes()` below.
+ *
+ * Two things about this loader are worth knowing before reading it:
+ *
+ * 1. An include is resolved with ONE query per association level, never a JOIN:
+ *    all parents are satisfied by a single `WHERE fk IN (...)`. That is
+ *    deliberate - it keeps the statement count constant in the number of rows -
+ *    but it is also why a per-include `limit` cannot simply be forwarded to that
+ *    query; see the per-parent window notes on `loadIncludes()`.
+ * 2. `{ all: true }` entries are expanded to one concrete include per
+ *    association before any of that happens; see `expandAllIncludes()`.
  */
 /** Minimal view of the association records kept in `Prorm.associations`. */
 export interface EagerLoadAssociation {
@@ -52,6 +62,49 @@ export declare function resolvePrimaryKeyAttr(m: any): string;
  * foreign-key logic to it.
  */
 export declare function resolveIncludeAssociation(ctx: EagerLoadContext, parentModel: any, parentModelName: string, includeOpt: any): EagerLoadAssociation;
+/**
+ * Expand `{ all: true }` / `{ all: 'alias' }` include entries into one concrete
+ * include per association.
+ *
+ * `loadIncludes()` used to open each iteration with `if (!includeOpt.model)
+ * continue`, so an entry carrying no `model` - which is exactly what
+ * `{ all: true }` is - was skipped without a word: `include: [{ all: true }]`
+ * emitted the parent SELECT and attached nothing. The class-based path expanded
+ * it (models/model.ts) and the `prorm.define()` path did not, so which of the
+ * two APIs you had used decided whether the option existed.
+ *
+ * Bounding the recursion. `nested: true` walks the association graph, and that
+ * graph routinely contains cycles (`User.hasMany(Post)` + `Post.belongsTo(User)`)
+ * and self-references (`Category.hasMany(Category)`). Depth alone does not bound
+ * those usefully here: unlike the class-based expander - which builds one SQL
+ * statement - every expanded include is another round trip, so a cycle across a
+ * model with three associations would reach 3^10 queries before the depth cap
+ * bit. So expansion is bounded twice: by `MAX_ALL_EXPANSION_DEPTH`, and by the
+ * chain of models already expanded on the current branch - a model is never
+ * auto-expanded twice on one path, which terminates cycles and self-references
+ * at their first repeat.
+ *
+ * The chain stops *re-expansion*, not the association itself: `User` with
+ * `{ all: true, nested: true }` still loads `posts` and each post's `user` (that
+ * is one of Post's associations, and `all` means all), but stops there rather
+ * than walking back into User's associations again. So a two-model cycle costs
+ * three queries, not ten levels of ping-pong.
+ *
+ * Two deliberate differences from the class-based expander:
+ * - the depth cap only ever stops *automatic* expansion; a hand-written include
+ *   is passed through at any depth rather than silently dropped.
+ * - an unknown `{ all: 'alias' }` is an error rather than a console warning.
+ *
+ * `required` carried onto an expanded include filters parents like any other
+ * required include. That needs expansion to happen before the parent-filtering
+ * pass rather than inside `loadIncludes()` at the end of the query - the
+ * filtering pass calls `resolveRequiredIncludeFilter`, which returns null for an
+ * entry with no `model`, so while `{ all: true }` was still un-expanded at that
+ * point `{ all: true, required: true }` loaded the associations and narrowed
+ * nothing. Callers therefore expand once, up front; expansion is idempotent, so
+ * `loadIncludes()` re-running it on an already-expanded list is a no-op.
+ */
+export declare function expandAllIncludes(ctx: EagerLoadContext, parentModel: any, parentModelName: string, includeList: any[], depth?: number, chain?: readonly string[]): any[];
 /**
  * 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
@@ -75,6 +128,18 @@ export declare function resolveRequiredIncludeFilter(ctx: EagerLoadContext, pare
     parentAttr: string;
     values: any[];
 } | null>;
+/**
+ * Attach a count of related rows to each parent, without loading them.
+ *
+ * `findAll({ withCount: ['posts'] })` sets `row.postsCount` on every parent.
+ * The counts are resolved with one grouped query per association, so this stays
+ * a constant number of statements no matter how many parents there are - the
+ * naive alternative is a count query per row.
+ *
+ * Use this when you need "how many" but not the rows themselves; a full
+ * `include` fetches every child just to measure the array.
+ */
+export declare function loadCounts(ctx: EagerLoadContext, parentRows: any[], parentModel: any, parentModelName: string, aliases: string[]): Promise<void>;
 /**
  * Eager-load `includeList` onto `parentRows`, recursing into nested includes.
  *
@@ -82,5 +147,39 @@ export declare function resolveRequiredIncludeFilter(ctx: EagerLoadContext, pare
  * 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.
+ *
+ * ## Per-include `limit` / `offset`
+ *
+ * `include: [{ model: Post, order: [['id', 'DESC']], limit: 5 }]` reads as "the
+ * 5 most recent posts *per user*", and that is what it now means. Getting there
+ * needs care, because one query serves every parent:
+ *
+ *   SELECT ... FROM "posts" WHERE "userId" IN (1, 2, 3) ORDER BY "id" DESC
+ *
+ * Forwarding `LIMIT 5` into that statement would cap the *whole result set* at 5
+ * rows - user 1 would get five posts and users 2 and 3 none - which is worse
+ * than the old behaviour of dropping the option, because the answer looks
+ * plausible while being wrong for every parent but the first. So the limit is
+ * never forwarded into a multi-parent `IN (...)` query. Instead:
+ *
+ * - `order` is still applied *in SQL*, so the database decides which rows come
+ *   first - the window is a window over the ordering the caller asked for, not
+ *   over insertion order.
+ * - the window is then applied per parent, in memory, when the fetched rows are
+ *   grouped onto their parents.
+ * - the one case where the shared query and a per-parent window coincide is a
+ *   single parent row (`findByPk(...)` with an include, the common case): there
+ *   `LIMIT`/`OFFSET` *are* pushed down to SQL, for `hasMany` only - see below.
+ *
+ * What this does NOT do: reduce what crosses the wire for multi-parent queries.
+ * All matching children are fetched and most of them are then discarded.
+ * `limit` here bounds the arrays you get back, it is not a transfer
+ * optimization. Doing better needs per-parent SQL windows (`ROW_NUMBER() OVER
+ * (PARTITION BY ...)` or `LATERAL`), which is a dialect-level feature this
+ * loader - which only ever calls `Model.findAll()` - cannot express today.
+ *
+ * `limit`/`offset` are only meaningful on a to-many include. On `belongsTo` and
+ * `hasOne` the result is a single row rather than a list, so they are reported
+ * and ignored rather than quietly accepted.
  */
 export declare function loadIncludes(ctx: EagerLoadContext, parentRows: any[], parentModel: any, parentModelName: string, includeList: any[]): Promise<void>;