or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

data-source.mdentity-definition.mdentity-schema.mdevents.mdfind-options.mdindex.mdmigrations.mdquery-builder.mdrelationships.mdrepository.md
tile.json

tessl/npm-typeorm

Data-Mapper ORM for TypeScript and ES2021+ supporting MySQL/MariaDB, PostgreSQL, MS SQL Server, Oracle, SAP HANA, SQLite, MongoDB databases.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/typeorm@0.3.x

To install, run

npx @tessl/cli install tessl/npm-typeorm@0.3.0

index.mddocs/

TypeORM

TypeORM is a comprehensive Object-Relational Mapping (ORM) library for TypeScript and JavaScript that supports both Data Mapper and Active Record patterns. It provides database abstraction for multiple database systems including MySQL/MariaDB, PostgreSQL, MS SQL Server, Oracle, SAP HANA, SQLite, and MongoDB, with features like entity management, repositories, migrations, transactions, associations, and query builders.

Package Information

  • Package Name: typeorm
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install typeorm

Core Imports

import { DataSource, Entity, Column, PrimaryGeneratedColumn, Repository } from "typeorm";

For CommonJS:

const { DataSource, Entity, Column, PrimaryGeneratedColumn, Repository } = require("typeorm");

Basic Usage

import { DataSource, Entity, Column, PrimaryGeneratedColumn } from "typeorm";

// Define an entity
@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;

  @Column()
  email: string;
}

// Create a data source (connection)
const dataSource = new DataSource({
  type: "postgres",
  host: "localhost",
  port: 5432,
  username: "test",
  password: "test",
  database: "test",
  entities: [User],
  synchronize: true,
});

// Initialize and use
await dataSource.initialize();
const userRepository = dataSource.getRepository(User);
const user = await userRepository.save({ name: "John", email: "john@example.com" });

Architecture

TypeORM is built around several key components:

  • DataSource: Central connection management and configuration point
  • Entities: Class-based models representing database tables using decorators
  • Repositories: Data access layer providing CRUD operations and custom queries
  • Query Builder: Fluent API for building complex SQL queries programmatically
  • Entity Manager: Direct database operations interface with transaction support
  • Migration System: Version control for database schema changes
  • Decorator System: Extensive metadata definition using TypeScript decorators

Capabilities

Data Source Management

Central connection and configuration management for database interactions. Replaces the deprecated Connection API with enhanced features and cleaner architecture.

class DataSource {
  constructor(options: DataSourceOptions);
  initialize(): Promise<DataSource>;
  destroy(): Promise<void>;
  getRepository<Entity>(target: EntityTarget<Entity>): Repository<Entity>;
  getTreeRepository<Entity>(target: EntityTarget<Entity>): TreeRepository<Entity>;
  transaction<T>(runInTransaction: (manager: EntityManager) => Promise<T>): Promise<T>;
  query(query: string, parameters?: any[]): Promise<any>;
  readonly isInitialized: boolean;
  readonly manager: EntityManager;
}

type DataSourceOptions = MysqlConnectionOptions | PostgresConnectionOptions | SqliteConnectionOptions | MongoConnectionOptions | /* ... other database types */;

Data Source Management

Entity Definition

Comprehensive entity definition system using TypeScript decorators for defining database schemas, relationships, and constraints with compile-time type safety.

function Entity(options?: EntityOptions): ClassDecorator;
function Column(options?: ColumnOptions): PropertyDecorator;
function PrimaryColumn(options?: ColumnOptions): PropertyDecorator;
function PrimaryGeneratedColumn(strategy?: "increment" | "identity" | "uuid", options?: ColumnOptions): PropertyDecorator;
function CreateDateColumn(options?: ColumnOptions): PropertyDecorator;
function UpdateDateColumn(options?: ColumnOptions): PropertyDecorator;

interface EntityOptions {
  name?: string;
  database?: string;
  schema?: string;
  engine?: string;
  synchronize?: boolean;
  orderBy?: Record<string, "ASC" | "DESC">;
}

Entity Definition

Relationship Management

Powerful relationship definition system supporting one-to-one, one-to-many, many-to-one, and many-to-many associations with advanced configuration options.

function OneToOne<T>(typeFunctionOrTarget: string | ((type?: any) => ObjectType<T>), options?: RelationOptions): PropertyDecorator;
function OneToMany<T>(typeFunctionOrTarget: string | ((type?: any) => ObjectType<T>), inverseSide: string | ((object: T) => any), options?: RelationOptions): PropertyDecorator;
function ManyToOne<T>(typeFunctionOrTarget: string | ((type?: any) => ObjectType<T>), options?: RelationOptions): PropertyDecorator;
function ManyToMany<T>(typeFunctionOrTarget: string | ((type?: any) => ObjectType<T>), options?: RelationOptions): PropertyDecorator;
function JoinColumn(options?: JoinColumnOptions | JoinColumnOptions[]): PropertyDecorator;
function JoinTable(options?: JoinTableOptions): PropertyDecorator;

Relationship Management

Repository Pattern

Type-safe repository pattern implementation providing CRUD operations, custom queries, and specialized repositories for different data access patterns.

class Repository<Entity> {
  save<T extends DeepPartial<Entity>>(entity: T, options?: SaveOptions): Promise<T & Entity>;
  save<T extends DeepPartial<Entity>>(entities: T[], options?: SaveOptions): Promise<(T & Entity)[]>;
  findOne(options: FindOneOptions<Entity>): Promise<Entity | null>;
  find(options?: FindManyOptions<Entity>): Promise<Entity[]>;
  findBy(where: FindOptionsWhere<Entity>): Promise<Entity[]>;
  remove(entity: Entity, options?: RemoveOptions): Promise<Entity>;
  remove(entities: Entity[], options?: RemoveOptions): Promise<Entity[]>;
  delete(criteria: string | string[] | number | number[] | Date | Date[] | ObjectID | ObjectID[] | FindOptionsWhere<Entity>): Promise<DeleteResult>;
  createQueryBuilder(alias?: string): SelectQueryBuilder<Entity>;
}

class TreeRepository<Entity> extends Repository<Entity> {
  findTrees(options?: FindTreeOptions): Promise<Entity[]>;
  findAncestors(entity: Entity, options?: FindTreeOptions): Promise<Entity[]>;
  findDescendants(entity: Entity, options?: FindTreeOptions): Promise<Entity[]>;
}

Repository Pattern

Query Building

Powerful query builder providing fluent API for constructing complex SQL queries with type safety and database-agnostic syntax.

class SelectQueryBuilder<Entity> {
  select(selection?: string | string[]): SelectQueryBuilder<Entity>;
  addSelect(selection: string | string[]): SelectQueryBuilder<Entity>;
  where(where: string | ((qb: SelectQueryBuilder<Entity>) => string) | Brackets | ObjectLiteral | ObjectLiteral[], parameters?: ObjectLiteral): SelectQueryBuilder<Entity>;
  andWhere(where: string | ((qb: SelectQueryBuilder<Entity>) => string) | Brackets | ObjectLiteral | ObjectLiteral[], parameters?: ObjectLiteral): SelectQueryBuilder<Entity>;
  orWhere(where: string | ((qb: SelectQueryBuilder<Entity>) => string) | Brackets | ObjectLiteral | ObjectLiteral[], parameters?: ObjectLiteral): SelectQueryBuilder<Entity>;
  leftJoin(property: string, alias: string, condition?: string, parameters?: ObjectLiteral): SelectQueryBuilder<Entity>;
  innerJoin(property: string, alias: string, condition?: string, parameters?: ObjectLiteral): SelectQueryBuilder<Entity>;
  orderBy(sort: string | ((alias: string) => string), order?: "ASC" | "DESC", nulls?: "NULLS FIRST" | "NULLS LAST"): SelectQueryBuilder<Entity>;
  groupBy(groupBy: string): SelectQueryBuilder<Entity>;
  having(having: string, parameters?: ObjectLiteral): SelectQueryBuilder<Entity>;
  limit(limit?: number): SelectQueryBuilder<Entity>;
  offset(offset?: number): SelectQueryBuilder<Entity>;
  getOne(): Promise<Entity | null>;
  getMany(): Promise<Entity[]>;
  getRawOne(): Promise<any>;
  getRawMany(): Promise<any[]>;
}

Query Building

Find Options & Operators

Type-safe find options system with powerful query operators for building complex where conditions without raw SQL.

interface FindOneOptions<Entity = any> {
  select?: FindOptionsSelect<Entity>;
  where?: FindOptionsWhere<Entity>[] | FindOptionsWhere<Entity>;
  relations?: FindOptionsRelations<Entity>;
  order?: FindOptionsOrder<Entity>;
  cache?: boolean | number | { id: any; milliseconds: number };
  lock?: { mode: "optimistic"; version: number | Date } | { mode: "pessimistic_read" | "pessimistic_write" | "dirty_read" | "pessimistic_partial_write" | "pessimistic_write_or_fail" | "for_no_key_update" };
  withDeleted?: boolean;
  loadRelationIds?: boolean | FindOptionsRelationIds;
  relationLoadStrategy?: "join" | "query";
}

function Equal(value: any): FindOperator<any>;
function Not(value: any): FindOperator<any>;
function LessThan(value: any): FindOperator<any>;
function MoreThan(value: any): FindOperator<any>;
function In(values: any[]): FindOperator<any>;
function Like(value: string): FindOperator<string>;
function Between(from: any, to: any): FindOperator<any>;
function IsNull(): FindOperator<any>;

Find Options & Operators

Migration System

Database schema version control system for managing database structure changes, data migrations, and deployment workflows.

interface MigrationInterface {
  up(queryRunner: QueryRunner): Promise<any>;
  down(queryRunner: QueryRunner): Promise<any>;
}

class Migration {
  constructor(id: number | string, timestamp: number, name: string, instance?: MigrationInterface);
  readonly id: number | string;
  readonly timestamp: number;
  readonly name: string;
  readonly instance?: MigrationInterface;
}

class MigrationExecutor {
  executePendingMigrations(): Promise<Migration[]>;
  undoLastMigration(): Promise<void>;
  showMigrations(): Promise<boolean>;
}

Migration System

Entity Schema (Code-First)

Code-first entity definition system allowing dynamic entity creation without decorators, ideal for runtime schema generation.

class EntitySchema<T = any> {
  constructor(options: EntitySchemaOptions<T>);
  readonly options: EntitySchemaOptions<T>;
}

interface EntitySchemaOptions<T> {
  name: string;
  target?: Function;
  tableName?: string;
  database?: string;
  schema?: string;
  columns: { [P in keyof T]: EntitySchemaColumnOptions };
  relations?: { [key: string]: EntitySchemaRelationOptions };
  indices?: EntitySchemaIndexOptions[];
  uniques?: EntitySchemaUniqueOptions[];
  checks?: EntitySchemaCheckOptions[];
  exclusions?: EntitySchemaExclusionOptions[];
}

Entity Schema

Event System & Subscribers

Comprehensive entity lifecycle event system with hooks and subscribers for implementing cross-cutting concerns like auditing, validation, and caching.

interface EntitySubscriberInterface<Entity = any> {
  listenTo?(): ObjectType<Entity> | Function | string;
  afterLoad?(entity: Entity, event?: LoadEvent<Entity>): Promise<any> | void;
  beforeInsert?(event: InsertEvent<Entity>): Promise<any> | void;
  afterInsert?(event: InsertEvent<Entity>): Promise<any> | void;
  beforeUpdate?(event: UpdateEvent<Entity>): Promise<any> | void;
  afterUpdate?(event: UpdateEvent<Entity>): Promise<any> | void;
  beforeRemove?(event: RemoveEvent<Entity>): Promise<any> | void;
  afterRemove?(event: RemoveEvent<Entity>): Promise<any> | void;
}

function EventSubscriber(): ClassDecorator;
function BeforeInsert(): MethodDecorator;
function AfterInsert(): MethodDecorator;
function BeforeUpdate(): MethodDecorator;
function AfterUpdate(): MethodDecorator;
function BeforeRemove(): MethodDecorator;
function AfterRemove(): MethodDecorator;

Event System & Subscribers

Core Types

type EntityTarget<Entity> = ObjectType<Entity> | EntitySchema<Entity> | string;
type ObjectType<T> = { new (): T } | Function;
interface ObjectLiteral { [key: string]: any; }
type DeepPartial<T> = { [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P]; };

enum DatabaseType {
  "mysql" = "mysql",
  "postgres" = "postgres",
  "cockroachdb" = "cockroachdb",
  "sqlite" = "sqlite",
  "better-sqlite3" = "better-sqlite3",
  "oracle" = "oracle",
  "mssql" = "mssql",
  "mongodb" = "mongodb"
}