typeorm/typeorm

TypeScript & JavaScript ORM for Node.js — supports PostgreSQL, MySQL, MariaDB, SQLite, SQL Server, Oracle, and more.

12 hidden assumptions · 6-stage pipeline · 10 components

Hidden Assumptions

Most of what this code assumes is routine. These 3 are the ones most likely to cause trouble here. The rest are minor; they're under "Show everything".

Open the standalone hidden-assumptions report for typeorm →

How Data Flows Through the System

Data enters through entity decorators that get collected into MetadataArgsStorage during class definition. When DataSource initializes, ConnectionMetadataBuilder processes these into EntityMetadata objects. User queries flow through Repository or EntityManager APIs, get transformed into QueryBuilder instances, then compiled by database-specific drivers into native SQL/NoSQL. Results return through QueryRunner back to EntityManager, which maps raw data into typed entity instances using the metadata.

1. Entity Definition Processing — Decorators like @Entity, @Column, @ManyToOne execute during class definition, calling getMetadataArgsStorage() to register EntityMetadataArgs, ColumnMetadataArgs, and RelationMetadataArgs in global storage [TypeScript classes with decorators → MetadataArgsStorage collections]
2. Metadata Compilation — DataSource.initialize() creates ConnectionMetadataBuilder which processes MetadataArgsStorage contents, validates relationships, and builds complete EntityMetadata objects with table names, column mappings, and relation definitions [MetadataArgsStorage collections → EntityMetadata]
3. Query Construction — Repository methods like find() or EntityManager operations convert FindOptions into SelectQueryBuilder instances, applying joins, conditions, ordering using EntityMetadata to ensure type safety [FindOptions → QueryBuilder Result]
4. Query Translation — Database-specific drivers (PostgresDriver, MysqlDriver, etc.) compile QueryBuilder instances into native SQL using their buildSelectSql() methods, handling dialect differences and parameter binding [QueryBuilder Result → Native SQL queries]
5. Query Execution — QueryRunner executes SQL against database connection pools, handling transactions, connection management, and returning raw database results with affected row counts and generated IDs [Native SQL queries → QueryRunnerResult]
6. Result Mapping — EntityManager transforms raw QueryRunnerResult data back into typed entity instances using EntityMetadata column mappings, handling nested relations and lazy loading proxies [QueryRunnerResult → Entity instances]

Data Models

The data structures that flow between stages — the contracts that hold the system together.

System Behavior

How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Feedback Loops

• Query Result Caching (cache-invalidation, balancing) — Trigger: Repository save/update/delete operations. Action: QueryResultCacheFactory clears cached results for affected entity types. Exit: Cache entries expire based on TTL or explicit invalidation.
• Connection Pool Management (auto-scale, balancing) — Trigger: High query volume or connection exhaustion. Action: Driver creates additional connections up to maximum pool size, releases idle connections after timeout. Exit: Query load returns to normal levels.
• Transaction Retry (retry, balancing) — Trigger: Deadlock or serialization failure errors. Action: QueryRunner retries transaction with exponential backoff. Exit: Transaction succeeds or maximum retry count reached.
• Lazy Relation Loading (recursive, reinforcing) — Trigger: Accessing lazy-loaded relation property. Action: RelationLoader creates new QueryBuilder to fetch related entities, which may trigger additional lazy loads. Exit: All requested relations are loaded into memory.

Delays

• DataSource Initialization (compilation, ~100-2000ms depending on entity count) — Application cannot perform database operations until metadata compilation and driver connection complete
• Query Result Cache TTL (cache-ttl, ~Configurable, default varies by cache provider) — Cached queries return stale data until cache expires and fresh query executes
• Connection Pool Warmup (warmup, ~50-500ms per connection) — First queries to a DataSource may be slower while connections are established
• Migration Execution Window (batch-window, ~Varies by migration complexity) — Database may be locked or partially available during schema changes

Control Points

• Database Type Selection (architecture-switch) — Controls: Which driver implementation is loaded and how queries are compiled - changes SQL dialect, feature availability, and performance characteristics. Default: One of: mysql, postgres, sqlite, mssql, oracle, mongodb, cockroachdb, spanner, sap
• Synchronization Mode (feature-flag) — Controls: Whether DataSource automatically creates/updates database schema to match entity metadata - dangerous in production. Default: synchronize: boolean (default false)
• Query Logging Level (env-var) — Controls: Which database operations are logged - affects debugging visibility and performance overhead. Default: all | error | schema | warn | info | log | migration
• Connection Pool Size (runtime-toggle) — Controls: Maximum concurrent connections and connection timeout behavior - affects concurrency and resource usage. Default: acquireTimeout, connectionLimit, idleTimeout per driver
• Entity Pattern Modes (architecture-switch) — Controls: Whether entities use Active Record (BaseEntity.save()) or Data Mapper (repository.save()) patterns. Default: Determined by entity class inheritance and repository usage

Technology Stack

Key Components

• DataSource (orchestrator) — Central coordinator that initializes database connections, manages entity metadata, provides access to EntityManager and Repositories, and handles migrations src/data-source/DataSource.ts
• ConnectionMetadataBuilder (processor) — Scans entity classes for decorators, builds EntityMetadata objects from decorator arguments, validates relationships and constraints src/connection/ConnectionMetadataBuilder.ts
• SelectQueryBuilder (transformer) — Fluent API for building SELECT queries - chains methods like .select(), .where(), .join() to construct type-safe SQL queries src/query-builder/SelectQueryBuilder.ts
• EntityManager (gateway) — Primary API for database operations - provides find(), save(), remove(), transaction() methods that work with any entity type src/entity-manager/EntityManager.ts
• Driver (adapter) — Abstract interface implemented by database-specific drivers to translate generic queries into native SQL/NoSQL and manage connections src/driver/Driver.ts
• Repository (gateway) — Entity-specific data access layer that provides typed CRUD operations (find, save, delete) with built-in query building and relationship management src/repository/Repository.ts
• MetadataArgsStorage (registry) — Global singleton that collects decorator metadata during class definition - stores entity args, column args, relation args before they are processed into EntityMetadata src/globals.ts
• QueryRunner (executor) — Database-specific query execution engine that handles transactions, creates/drops tables, executes raw SQL, and manages database schema changes src/query-runner/QueryRunner.ts
• SchemaBuilder (transformer) — Compares current EntityMetadata with existing database schema and generates DDL statements to synchronize database structure with entity definitions src/schema-builder/SchemaBuilder.ts
• MigrationExecutor (orchestrator) — Manages database migration lifecycle - discovers migration files, tracks executed migrations in database table, executes pending migrations in order src/migration/MigrationExecutor.ts

Related Library Repositories

Frequently Asked Questions

Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.