Relations with decorators

Four decorators, one per association kind. Each takes a thunk — () => Post
rather than Post — so two models can point at each other across imports
without one of them being undefined at load time.

import {
  DataTypes, Model, Table, Column, PrimaryKey, AutoIncrement,
  HasMany, BelongsTo, HasOne, BelongsToMany,
} from 'ts-prorm-orm';

@Table({ tableName: 'users' })
class User extends Model {
  @Column(DataTypes.INTEGER())
  @PrimaryKey
  @AutoIncrement
  declare id: number;

  @Column(DataTypes.STRING(100))
  declare name: string;

  @HasMany(() => Post, { foreignKey: 'userId', as: 'posts' })
  declare posts?: Post[];

  @HasOne(() => Profile, { foreignKey: 'userId', as: 'profile' })
  declare profile?: Profile;
}

@Table({ tableName: 'posts' })
class Post extends Model {
  @Column(DataTypes.INTEGER())
  @PrimaryKey
  @AutoIncrement
  declare id: number;

  @Column(DataTypes.STRING(200))
  declare title: string;

  @Column(DataTypes.INTEGER())
  declare userId: number;

  @BelongsTo(() => User, { foreignKey: 'userId', as: 'author' })
  declare author?: User;

  @BelongsToMany(() => Tag, { through: 'post_tags', foreignKey: 'postId', otherKey: 'tagId', as: 'tags' })
  declare tags?: Tag[];
}

The four decorators, as tables:

Registering them

const Users = prorm.addModel(User);
const Posts = prorm.addModel(Post);
const Tags  = prorm.addModel(Tag);
await prorm.sync();

Order does not matter. Associations are queued when a model is registered and
bound as soon as both ends exist — otherwise registering Post before User
would bind against a class that had never been through define(), and the
foreign key would quietly not be created.

With Profile and Tag as plain id + one column models, sync() creates
five tables — the junction comes from through: 'post_tags':

The generated SQL, PostgreSQL

Each association also adds helper methods to the rows. A loaded Post gets
getAuthor, setAuthor, unsetAuthor, createAuthor, hasAuthor,
countAuthor from @BelongsTo, and getTags, addTag, addTags,
removeTag, setTags, countTags, hasTag from @BelongsToMany:

const post = await Posts.findByPk(1);
const math = await Tags.create({ name: 'math' });

await post.addTag(math);   // INSERT INTO "post_tags" ("postId", "tagId") VALUES (1, 1)
await post.getTags();      // [{ id: 1, name: 'math', … }]

Loading

const users = await Users.findAll({
  include: [
    { model: Posts, as: 'posts' },
    { model: Profiles, as: 'profile' },
  ],
});

users[0].posts?.forEach((post) => console.log(post.title));
users[0].profile?.bio;

One query per level — the parents, then each association by key:

A many-to-many include goes through the junction, so it is two queries for
that level:

const posts = await Posts.findAll({ include: [{ model: Tags, as: 'tags' }] });

The as in the include must match the as on the decorator — that name is how
the two are matched, and how the loaded rows are attached. A mismatch fails
after the parent query has run, naming the aliases that do exist:

User has no association to Post aliased 'articles'. Available: posts

Referential actions

class Post extends Model {
  @BelongsTo(() => User, {
    foreignKey: 'userId',
    as: 'author',
    onDelete: 'CASCADE',
    onUpdate: 'RESTRICT',
  })
  declare author?: User;
}

sync() puts the actions on the foreign key. On PostgreSQL:

[!IMPORTANT]
When both sides declare the key (@HasMany on User and @BelongsTo on
Post), the association registered first sets the reference, so put the
actions on both when you are not sure which that is. Before 4.9.2 neither
onDelete nor onUpdate reached the table; see
Foreign keys and constraints
for tables created by an older release.

A note on the property type

Mark the association optional (posts?: Post[]) — it is only populated when
you include it. Under strict, that forces the check at every use, which is
the correct shape: a user loaded without its posts genuinely has none loaded.

In a fully typed model, wrap it in NonAttribute as well so it stays out of
the inferred create/read shapes — see
Relations in TypeScript.

Associations — every option, including scoped and polymorphic

Eager loading

Relations with decorators

Registering them#

Loading#

Referential actions#

A note on the property type#

Next#

Registering them

Loading

Referential actions

A note on the property type

Next