![](https://raw.githubusercontent.com/ScaleLeap/typeorm/master/docs/assets/header.png)

📦 @scaleleap/typeorm
===================================

Enhanced and pre-configured TypeORM version with helpers included.

---

## Download & Installation

```sh
$ npm i -s typeorm @scaleleap/typeorm
```

Create a config file in `src/ormconfig.ts`:

```ts
import { createConnectionOptions } from '@scaleleap/typeorm'

export = createConnectionOptions({
  // ... your config
})
```

Add the following to `package.json`:

```json
{
  "scripts": {
    "typeorm": "typeorm-cli -f src/ormconfig.ts"
  }
}
```

Add the following to `tsconfig.json`:

```json
{
  "compilerOptions": {
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true,
  },
}
```

## Usage

Our package is a superset of `typeorm`, and thus you can use it exactly the same way as you would
use `typeorm` directly.

```ts
import { createConnection } from '@scaleleap/typeorm'
```

## Enhancements

### `typeorm-cli` CLI replacement that supports TypeScript config files

```sh
typeorm-cli migration:generate ...
```

Here is a list of features and enhancements over stock `typeorm`:

### `createConnectionOptions` factory function

Factory function for creating TypeORM configuration object. Suitable to be passed to `createConnection`
function or inside `ormconfig.ts`.

#### Logger

You can pass an instance of `@scaleleap/logger` to `createConnectionOptions` factory to be used
as a custom logger for TypeORM.

#### Naming Strategy

This package is pre-configured to use a custom naming strategy that is more descriptive and sane
than TypeORM default. It uses meaningful identity naming. E.g. instead of
`PK_adc83b19e793491b1c6ea0fd8b46cd9f32e592fc` it will use `pk_user_id_a4378d`.

### `createConnection` factory function

The stock `createConnection` is amended to return a connection with enhanced type that exposes
PostgreSQL connection Pool via `connection.driver.master`. The prop was already there, we are just
casting the connection and driver to the right type to expose it correctly.

### `createEncryptionTransformer` factory function

Creates a [column transformer](https://github.com/typeorm/typeorm/blob/master/docs/entities.md#column-options)
which can then be used to encrypt data.

```ts
export class Encrypted {
  // ...

  @Column({ transformer: createEncryptionTransformer(encryptionKey) })
  public secret!: string
}
```

### `migration:generate`

The `migration:generate` command has been enhanced to create prettified SQL.

### `TestDatabaseConnection` class for tests

```ts
// pass the same params as `createConnectionOptions`
const tdc = new TestDatabaseConnection({
  connectionOptions: {
    entities: [User],
  },
})

// 1. Creates a test database
// 2. Returns TypeORM connection
const connection = await tdc.setup()

//
// run the tests here...
//

// 1. Destroys the test database
// 2. Disconnects
await tdc.teardown()
```

### `upsert` function - WIP

Technically the code is ready. But an
[issue with TypeORM](https://github.com/typeorm/typeorm/issues/1090#issuecomment-615556201)
is preventing us from using it.

## New features

### `QidTransformer`

A transformer to convert UUID strings to [Qid](https://github.com/ozra/iid) and back.

See [test/entities/qid.ts](test/entities/qid.ts) for usage example.

## Contributing

This repository uses [Conventional Commit](https://www.conventionalcommits.org/) style commit messages.

## Authors or Acknowledgments

* Roman Filippov ([Scale Leap](https://www.scaleleap.com))

## License

This project is licensed under the MIT License.

## Badges

[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/ScaleLeap/typeorm/CI)](https://github.com/ScaleLeap/typeorm/actions)
[![NPM](https://img.shields.io/npm/v/@scaleleap/typeorm)](https://npm.im/@scaleleap/typeorm)
[![License](https://img.shields.io/npm/l/@scaleleap/typeorm)](./LICENSE)
[![Coveralls](https://img.shields.io/coveralls/github/scaleleap/typeorm)](https://coveralls.io/github/ScaleLeap/typeorm)
[![Semantic Release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg)](https://github.com/semantic-release/semantic-release)