Skip to content

Commit 1962bb8

Browse files
gioboagioboa
authored
Merge branch 'master' into patch-1
2 parents 76949bc + 35ca51a commit 1962bb8

File tree

1,385 files changed

+29419
-41336
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

1,385 files changed

+29419
-41336
lines changed

.nycrc.json renamed to .c8rc.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22
"all": true,
33
"cache": false,
44
"exclude": ["**/*.d.ts"],
5+
"exclude-after-remap": true,
56
"extension": [".ts"],
67
"include": ["build/compiled/src/**", "src/**"],
7-
"reporter": "lcov"
8+
"reporter": ["lcov"]
89
}

‎.github/FUNDING.yml‎

Lines changed: 0 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,3 @@
11
# These are supported funding model platforms
22

3-
github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
4-
patreon: # Replace with a single Patreon username
53
open_collective: typeorm
6-
ko_fi: # Replace with a single Ko-fi username
7-
tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
8-
custom: # Replace with a single custom sponsorship URL

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,8 @@
3333

3434
- [ ] Code is up-to-date with the `master` branch
3535
- [ ] This pull request links relevant issues as `Fixes #00000`
36-
- [ ] There are new or updated unit tests validating the change
37-
- [ ] Documentation has been updated to reflect this change
36+
- [ ] There are new or updated tests validating the change (`tests/**.test.ts`)
37+
- [ ] Documentation has been updated to reflect this change (`docs/docs/**.md`)
3838

3939
<!--
4040
🎉 Thank you for contributing and making TypeORM even better!

‎.github/copilot-instructions.md‎

Lines changed: 297 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,297 @@
1+
# GitHub Copilot Instructions for TypeORM
2+
3+
This document provides guidance for GitHub Copilot when working with the TypeORM codebase.
4+
5+
## Project Overview
6+
7+
TypeORM is a TypeScript-based Object-Relational Mapping (ORM) library that supports multiple databases including MySQL/MariaDB, PostgreSQL, MS SQL Server, Oracle, SAP HANA, SQLite, MongoDB, and Google Spanner. It implements both Active Record and Data Mapper patterns and runs on Node.js, Browser, React Native, and Electron platforms.
8+
9+
## Architecture & Structure
10+
11+
### Core Components
12+
13+
- **`src/data-source/`** - DataSource (formerly Connection) management
14+
- **`src/entity-manager/`** - Entity management and operations
15+
- **`src/repository/`** - Repository pattern implementation
16+
- **`src/query-builder/`** - SQL query building
17+
- **`src/decorator/`** - TypeScript decorators for entities, columns, relations
18+
- **`src/driver/`** - Database-specific drivers
19+
- **`src/metadata/`** - Entity metadata management
20+
- **`src/schema-builder/`** - Schema creation and migration
21+
- **`src/migration/`** - Database migration system
22+
- **`src/subscriber/`** - Event subscriber system
23+
- **`src/persistence/`** - Entity persistence logic
24+
25+
### Design Patterns
26+
27+
- **Active Record Pattern**: Entities have methods to save, remove, and query themselves
28+
- **Data Mapper Pattern**: Repositories handle entity persistence separately from business logic
29+
- **Decorator Pattern**: Extensive use of TypeScript decorators for metadata definition
30+
- **Builder Pattern**: QueryBuilder for constructing complex queries
31+
32+
## Coding Standards
33+
34+
### TypeScript Configuration
35+
36+
- Target: ES2021+ with CommonJS modules
37+
- Decorators: `experimentalDecorators` and `emitDecoratorMetadata` enabled
38+
39+
### Code Style
40+
41+
- **Formatting**: Use Prettier with these settings:
42+
- No semicolons (`"semi": false`)
43+
- **Linting**: ESLint with TypeScript support
44+
- Use `@typescript-eslint` rules
45+
- Warnings allowed for some `@typescript-eslint/no-*` rules
46+
- Unused variables starting with `_` are ignored
47+
- **Naming Conventions**:
48+
- Classes: PascalCase (e.g., `DataSource`, `EntityManager`)
49+
- Interfaces: PascalCase (e.g., `ColumnOptions`, `RelationOptions`)
50+
- Variables/functions: camelCase
51+
- Constants: UPPER_SNAKE_CASE for true constants
52+
- Private members: Use standard camelCase (no underscore prefix)
53+
54+
### TypeScript Patterns
55+
56+
- Use explicit types for public APIs
57+
- Prefer interfaces over type aliases for object shapes
58+
- Use generics for reusable components
59+
- Avoid `any` where possible; use `unknown` or proper types
60+
- Use optional chaining (`?.`) and nullish coalescing (`??`) operators
61+
- Leverage TypeScript utility types (`Partial<T>`, `Required<T>`, `Pick<T>`, etc.)
62+
63+
## Testing
64+
65+
### Test Structure
66+
67+
Tests are organized in `test/` directory:
68+
69+
- **`test/functional/`** - Feature and integration tests organized by functionality (preferred)
70+
- **`test/github-issues/`** - Tests for specific GitHub issues
71+
- **`test/unit/`** - Unit tests for individual components
72+
- **`test/utils/`** - Test utilities and helpers
73+
74+
**Note**: Prefer writing functional tests over per-issue tests.
75+
76+
### Test Writing Guidelines
77+
78+
1. **Use the standard test template**:
79+
80+
```typescript
81+
import { expect } from "chai"
82+
import "reflect-metadata"
83+
import {
84+
closeTestingConnections,
85+
createTestingConnections,
86+
reloadTestingDatabases,
87+
} from "../../utils/test-utils"
88+
import { DataSource } from "../../../src/data-source/DataSource"
89+
90+
describe("description of functionality", () => {
91+
let dataSources: DataSource[]
92+
before(
93+
async () =>
94+
(dataSources = await createTestingConnections({
95+
entities: [__dirname + "/entity/*{.js,.ts}"],
96+
schemaCreate: true,
97+
dropSchema: true,
98+
})),
99+
)
100+
beforeEach(() => reloadTestingDatabases(dataSources))
101+
after(() => closeTestingConnections(dataSources))
102+
103+
it("should do something specific", () =>
104+
Promise.all(
105+
dataSources.map(async (dataSource) => {
106+
// Test implementation
107+
}),
108+
))
109+
})
110+
```
111+
112+
2. **Test Configuration**:
113+
- Tests run against multiple databases (as configured in `ormconfig.json`)
114+
- Each test should work across all supported databases unless database-specific
115+
- Place entity files in `./entity/` relative to test file for automatic loading
116+
- Use `Promise.all(dataSources.map(...))` pattern to test against all databases
117+
118+
3. **Test Naming**:
119+
- Use descriptive `describe()` blocks for features
120+
- Use "should..." format for `it()` descriptions
121+
- Reference GitHub issue numbers when fixing specific issues
122+
123+
4. **Running Tests**:
124+
- Full test suite: `pnpm run test` (compiles then runs tests)
125+
- Fast iteration: `pnpm run test:fast` (runs without recompiling)
126+
- Specific tests: `pnpm run test:fast -- --grep "pattern"`
127+
- Watch mode: `pnpm run compile -- --watch` + `pnpm run test:fast`
128+
129+
## Database-Specific Considerations
130+
131+
### Multi-Database Support
132+
133+
When writing code or tests:
134+
135+
- Ensure compatibility across all supported databases
136+
- Use driver-specific code only in `src/driver/` directory
137+
- Test database-agnostic code against multiple databases
138+
- Use `DataSource.options.type` to check database type when needed
139+
- Be aware of SQL dialect differences (LIMIT vs TOP, etc.)
140+
141+
### Driver Implementation
142+
143+
Each driver in `src/driver/` implements common interfaces:
144+
145+
- Connection management
146+
- Query execution
147+
- Schema synchronization
148+
- Type mapping
149+
- Transaction handling
150+
151+
## Common Development Tasks
152+
153+
### Adding a New Feature
154+
155+
1. Create entities in appropriate test directory
156+
2. Write tests first (TDD approach encouraged)
157+
3. Implement feature in `src/`
158+
4. Ensure tests pass across all databases
159+
5. Update documentation if public API changes
160+
6. Follow commit message conventions
161+
162+
### Adding a New Decorator
163+
164+
1. Create decorator file in `src/decorator/`
165+
2. Create metadata args in `src/metadata-args/`
166+
3. Update metadata builder in `src/metadata-builder/`
167+
4. Export from `src/index.ts`
168+
5. Add comprehensive tests
169+
6. Update TypeScript type definitions if needed
170+
171+
### Working with Migrations
172+
173+
- Migrations are in `src/migration/`
174+
- Migration files should be timestamped
175+
- Support both up and down migrations
176+
- Test migrations against all supported databases
177+
- Ensure schema changes are reversible
178+
179+
## Build & Development Workflow
180+
181+
### Commands
182+
183+
- **Build**: `pnpm run compile` - Compiles TypeScript to `build/compiled/`
184+
- **Package**: `pnpm run package` - Creates distribution in `build/package/`
185+
- **Pack**: `pnpm pack` - Creates `.tgz` file in `build/`
186+
- **Test**: `pnpm run test` - Compile and run all tests
187+
- **Lint**: `pnpm run lint` - Run ESLint
188+
- **Format**: `pnpm run format` - Run Prettier
189+
- **Watch**: `pnpm run watch` - Watch mode for TypeScript compilation
190+
191+
### Development Setup
192+
193+
1. Install dependencies: `pnpm install`
194+
2. Copy config: `cp ormconfig.sample.json ormconfig.json`
195+
3. Configure database connections in `ormconfig.json`
196+
4. Optionally use Docker: `docker compose up` for database services
197+
198+
### Pre-commit Hooks
199+
200+
- Husky runs pre-commit hooks
201+
- Lint-staged runs on staged files
202+
- Format and lint checks must pass
203+
204+
## Contribution Guidelines
205+
206+
### Commit Message Format
207+
208+
Follow conventional commits:
209+
210+
```
211+
<type>: <subject>
212+
213+
<body>
214+
215+
<footer>
216+
```
217+
218+
**Types**: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `chore`, `revert`
219+
220+
**Subject**:
221+
222+
- Use imperative, present tense
223+
- Don't capitalize first letter
224+
- No period at the end
225+
- Max 100 characters per line
226+
227+
### Pull Request Requirements
228+
229+
- All tests must pass
230+
- Include appropriate tests for changes
231+
- Follow existing code style
232+
- Update documentation for API changes
233+
- Reference related GitHub issues
234+
- Get approval before merging
235+
236+
## Common Patterns & Idioms
237+
238+
### Entity Definition
239+
240+
```typescript
241+
@Entity()
242+
export class User {
243+
@PrimaryGeneratedColumn()
244+
id: number
245+
246+
@Column()
247+
name: string
248+
249+
@OneToMany(() => Photo, (photo) => photo.user)
250+
photos: Photo[]
251+
}
252+
```
253+
254+
### Repository Usage
255+
256+
```typescript
257+
const userRepository = dataSource.getRepository(User)
258+
const user = await userRepository.findOne({ where: { id: 1 } })
259+
```
260+
261+
### QueryBuilder
262+
263+
```typescript
264+
const users = await dataSource
265+
.getRepository(User)
266+
.createQueryBuilder("user")
267+
.leftJoinAndSelect("user.photos", "photo")
268+
.where("user.name = :name", { name: "John" })
269+
.getMany()
270+
```
271+
272+
### Transactions
273+
274+
```typescript
275+
await dataSource.transaction(async (manager) => {
276+
await manager.save(user)
277+
await manager.save(photo)
278+
})
279+
```
280+
281+
## Important Notes
282+
283+
- Always import `reflect-metadata` before TypeORM
284+
- Be careful with circular dependencies between entities
285+
- Use lazy relations or forward references for circular entity references
286+
- Connection pooling is handled automatically by drivers
287+
- Be mindful of N+1 query problems; use joins or eager loading
288+
- Repository methods are async; always use `await`
289+
- Entity instances should be plain objects, not class instances with methods (Data Mapper pattern)
290+
291+
## Resources
292+
293+
- [Main Documentation](https://typeorm.io)
294+
- [Contributing Guide](../CONTRIBUTING.md)
295+
- [Developer Guide](../DEVELOPER.md)
296+
- [GitHub Repository](https://github.com/typeorm/typeorm)
297+
- [Issue Tracker](https://github.com/typeorm/typeorm/issues)

‎.github/workflows/codeql.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ jobs:
2323

2424
steps:
2525
- name: Checkout repository
26-
uses: actions/checkout@v5
26+
uses: actions/checkout@v6
2727

2828
- name: Initialize CodeQL
2929
uses: github/codeql-action/init@v3

0 commit comments

Comments
 (0)