API репозиториев

Неофициальный Бета-перевод

Эта страница переведена PageTurner AI (бета). Не одобрена официально проектом. Нашли ошибку? Сообщить о проблеме →

API Repository

• manager - Используемый этим репозиторием EntityManager.

const manager = repository.manager

• metadata - EntityMetadata сущности, управляемой этим репозиторием.

const metadata = repository.metadata

• queryRunner - Построитель запросов, используемый EntityManager. Применяется только в транзакционных экземплярах EntityManager.

const queryRunner = repository.queryRunner

• target - Класс целевой сущности, управляемой этим репозиторием. Используется только в транзакционных экземплярах EntityManager.

const target = repository.target

• createQueryBuilder - Создает построитель запросов для формирования SQL-запросов. Подробнее о QueryBuilder.

const users = await repository
    .createQueryBuilder("user")
    .where("user.name = :name", { name: "John" })
    .getMany()

• hasId - Проверяет, определено ли свойство первичной колонки у указанной сущности.

if (repository.hasId(user)) {
    // ... do something
}

• getId - Получает значения свойств первичной колонки указанной сущности. При наличии составных первичных ключей возвращается объект с именами и значениями первичных колонок.

const userId = repository.getId(user) // userId === 1

• create - Создает новый экземпляр User. Дополнительно принимает объект со свойствами пользователя, которые будут записаны в созданный объект.

const user = repository.create() // same as const user = new User();
const user = repository.create({
    id: 1,
    firstName: "Timber",
    lastName: "Saw",
}) // same as const user = new User(); user.firstName = "Timber"; user.lastName = "Saw";

• merge - Объединяет несколько сущностей в одну.

const user = new User()
repository.merge(user, { firstName: "Timber" }, { lastName: "Saw" }) // same as user.firstName = "Timber"; user.lastName = "Saw";

• preload - Создает новую сущность из переданного объекта JavaScript. Если сущность уже существует в базе данных, она загружается (вместе со связанными данными), все её значения заменяются новыми из переданного объекта, и возвращается обновлённая сущность. Фактически возвращается сущность из БД с заменёнными свойствами.

  Примечание: переданный объект должен содержать идентификатор сущности / первичный ключ для поиска. Возвращает undefined, если сущность не найдена.

const partialUser = {
    id: 1,
    firstName: "Rizzrak",
    profile: {
        id: 1,
    },
}
const user = await repository.preload(partialUser)
// user will contain all missing data from partialUser with partialUser property values:
// { id: 1, firstName: "Rizzrak", lastName: "Saw", profile: { id: 1, ... } }

• save - Сохраняет указанную сущность или массив сущностей. Если сущность существует в базе данных, она обновляется. Если сущность отсутствует в базе данных, она добавляется. Все сущности сохраняются в одной транзакции (для отдельной сущности менеджер не является транзакционным). Поддерживает частичное обновление — неопределённые свойства пропускаются. Возвращает сохранённую сущность/сущности.

await repository.save(user)
await repository.save([category1, category2, category3])

• remove - Удаляет указанную сущность или массив сущностей. Все сущности удаляются в одной транзакции (для отдельной сущности менеджер не является транзакционным). Возвращает удалённую сущность/сущности.

await repository.remove(user)
await repository.remove([category1, category2, category3])

• insert - Добавляет новую сущность или массив сущностей.

await repository.insert({
    firstName: "Timber",
    lastName: "Timber",
})

await repository.insert([
    {
        firstName: "Foo",
        lastName: "Bar",
    },
    {
        firstName: "Rizz",
        lastName: "Rak",
    },
])

• update - Обновляет сущности по их id, массиву id или условиям. Устанавливает поля из частичного объекта сущности.

await repository.update({ age: 18 }, { category: "ADULT" })
// executes UPDATE user SET category = ADULT WHERE age = 18

await repository.update(1, { firstName: "Rizzrak" })
// executes UPDATE user SET firstName = Rizzrak WHERE id = 1

// optionally request RETURNING / OUTPUT values (supported drivers only)
const result = await repository.update(
    1,
    { firstName: "Rizzrak" },
    { returning: ["id", "firstName"] },
)
console.log(result.raw) // [{ id: 1, firstName: "Rizzrak" }]

• updateAll - Обновляет все сущности указанного типа (без условия WHERE). Устанавливает поля из частичного объекта сущности.

await repository.updateAll({ category: "ADULT" })
// executes UPDATE user SET category = ADULT

await repository.updateAll(
    { category: "ADULT" },
    { returning: "*" }, // limited to drivers that support returning clauses
)

• upsert - Добавляет новую сущность или массив сущностей, если они не существуют, либо обновляет существующие. Поддерживается в AuroraDataApi, Cockroach, Mysql, Postgres и Sqlite.

При обновлении во время upsert-операции (из-за конфликта) специальные колонки вроде @UpdateDateColumn и @VersionColumn автоматически обновляются.

await repository.upsert(
    [
        { externalId: "abc123", firstName: "Rizzrak" },
        { externalId: "bca321", firstName: "Karzzir" },
    ],
    ["externalId"],
)
/** executes
 *  INSERT INTO user
 *  VALUES
 *      (externalId = abc123, firstName = Rizzrak),
 *      (externalId = cba321, firstName = Karzzir),
 *  ON CONFLICT (externalId) DO UPDATE
 *  SET firstName = EXCLUDED.firstName,
 *      updatedDate = CURRENT_TIMESTAMP,
 *      version = version + 1
 **/

Также можно запросить возвращаемые значения после операции upsert (поддерживается драйверами с возможностями RETURNING / OUTPUT):

const { raw } = await repository.upsert(
    { externalId: "abc123", firstName: "Rizzrak" },
    {
        conflictPaths: ["externalId"],
        returning: ["externalId", "firstName"],
    },
)
console.log(raw) // [{ externalId: "abc123", firstName: "Rizzrak" }]

await repository.upsert(
    [
        { externalId: "abc123", firstName: "Rizzrak" },
        { externalId: "bca321", firstName: "Karzzir" },
    ],
    {
        conflictPaths: ["externalId"],
        skipUpdateIfNoValuesChanged: true, // supported by postgres, skips update if it would not change row values
        upsertType: "upsert", //  "on-conflict-do-update" | "on-duplicate-key-update" | "upsert" - optionally provide an UpsertType - 'upsert' is currently only supported by CockroachDB
    },
)
/** executes
 *  INSERT INTO user
 *  VALUES
 *      (externalId = abc123, firstName = Rizzrak),
 *      (externalId = cba321, firstName = Karzzir),
 *  ON CONFLICT (externalId) DO UPDATE
 *  SET firstName = EXCLUDED.firstName
 *  WHERE user.firstName IS DISTINCT FROM EXCLUDED.firstName
 **/

await repository.upsert(
    [
        { externalId: "abc123", firstName: "Rizzrak", dateAdded: "2020-01-01" },
        { externalId: "bca321", firstName: "Karzzir", dateAdded: "2022-01-01" },
    ],
    {
        conflictPaths: ["externalId"],
        skipUpdateIfNoValuesChanged: true, // supported by postgres, skips update if it would not change row values
        indexPredicate: "dateAdded > 2020-01-01", // supported by postgres, allows for partial indexes
    },
)
/** executes
 *  INSERT INTO user
 *  VALUES
 *      (externalId = abc123, firstName = Rizzrak, dateAdded = 2020-01-01),
 *      (externalId = cba321, firstName = Karzzir, dateAdded = 2022-01-01),
 *  ON CONFLICT (externalId) WHERE ( dateAdded > 2021-01-01 ) DO UPDATE
 *  SET firstName = EXCLUDED.firstName,
 *  SET dateAdded = EXCLUDED.dateAdded,
 *  WHERE user.firstName IS DISTINCT FROM EXCLUDED.firstName OR user.dateAdded IS DISTINCT FROM EXCLUDED.dateAdded
 **/

• delete - Удаляет сущности по идентификатору, массиву идентификаторов или условиям:

await repository.delete(1)
await repository.delete([1, 2, 3])
await repository.delete({ firstName: "Timber" })

• deleteAll - Удаляет все сущности указанного типа (без условия WHERE).

await repository.deleteAll()
// executes DELETE FROM user

См. также метод clear, который выполняет операцию TRUNCATE TABLE.

• softDelete и restore - Мягкое удаление и восстановление строки по идентификатору, массиву идентификаторов или условиям:

const repository = dataSource.getRepository(Entity)
// Soft delete an entity
await repository.softDelete(1)
// And you can restore it using restore;
await repository.restore(1)
// Soft delete multiple entities
await repository.softDelete([1, 2, 3])
// Or soft delete by other attribute
await repository.softDelete({ firstName: "Jake" })

• softRemove и recover - Альтернатива softDelete и restore.

// You can soft-delete them using softRemove
const entities = await repository.find()
const entitiesAfterSoftRemove = await repository.softRemove(entities)

// And You can recover them using recover;
await repository.recover(entitiesAfterSoftRemove)

• increment - Увеличивает значение столбца на указанную величину для сущностей, соответствующих условиям.

await repository.increment({ firstName: "Timber" }, "age", 3)

• decrement - Уменьшает значение столбца на указанную величину для сущностей, соответствующих условиям.

await repository.decrement({ firstName: "Timber" }, "age", 3)

• exists - Проверяет существование хотя бы одной сущности, соответствующей FindOptions.

const exists = await repository.exists({
    where: {
        firstName: "Timber",
    },
})

• existsBy - Проверяет существование хотя бы одной сущности, соответствующей FindOptionsWhere.

const exists = await repository.existsBy({ firstName: "Timber" })

• count - Считает сущности, соответствующие FindOptions. Полезно для пагинации.

const count = await repository.count({
    where: {
        firstName: "Timber",
    },
})

• countBy - Считает сущности, соответствующие FindOptionsWhere. Полезно для пагинации.

const count = await repository.countBy({ firstName: "Timber" })

• sum - Возвращает сумму числового поля для всех сущностей, соответствующих FindOptionsWhere.

const sum = await repository.sum("age", { firstName: "Timber" })

• average - Возвращает среднее значение числового поля для всех сущностей, соответствующих FindOptionsWhere.

const average = await repository.average("age", { firstName: "Timber" })

• minimum - Возвращает минимальное значение числового поля для всех сущностей, соответствующих FindOptionsWhere.

const minimum = await repository.minimum("age", { firstName: "Timber" })

• maximum - Возвращает максимальное значение числового поля для всех сущностей, соответствующих FindOptionsWhere.

const maximum = await repository.maximum("age", { firstName: "Timber" })

• find - Находит сущности, соответствующие FindOptions.

const timbers = await repository.find({
    where: {
        firstName: "Timber",
    },
})

• findBy - Находит сущности, соответствующие FindWhereOptions.

const timbers = await repository.findBy({
    firstName: "Timber",
})

• findAndCount - Находит сущности, соответствующие FindOptions. Дополнительно подсчитывает все подходящие сущности, игнорируя настройки пагинации (параметры from и take).

const [timbers, timbersCount] = await repository.findAndCount({
    where: {
        firstName: "Timber",
    },
})

• findAndCountBy - Находит сущности, соответствующие заданным FindOptionsWhere. Также подсчитывает все подходящие сущности, игнорируя параметры пагинации (from и take).

const [timbers, timbersCount] = await repository.findAndCountBy({
    firstName: "Timber",
})

• findOne - Находит первую сущность, соответствующую заданным FindOptions.

const timber = await repository.findOne({
    where: {
        firstName: "Timber",
    },
})

• findOneBy - Находит первую сущность, соответствующую заданным FindOptionsWhere.

const timber = await repository.findOneBy({ firstName: "Timber" })

• findOneOrFail - Находит первую сущность по ID или условиям поиска. Отклоняет промис, если совпадений не найдено.

const timber = await repository.findOneOrFail({
    where: {
        firstName: "Timber",
    },
})

• findOneByOrFail - Находит первую сущность, соответствующую заданным FindOptions. Отклоняет промис, если совпадений не найдено.

const timber = await repository.findOneByOrFail({ firstName: "Timber" })

• query - Выполняет сырой SQL-запрос.

const rawData = await repository.query(`SELECT * FROM USERS`)

// You can also use parameters to avoid SQL injection
// The syntax differs between the drivers

// aurora-mysql, better-sqlite3, capacitor, cordova,
// expo, mariadb, mysql, nativescript, react-native,
// sap, sqlite, sqljs
const rawData = await repository.query(
    "SELECT * FROM USERS WHERE name = ? and age = ?",
    ["John", 24],
)

// aurora-postgres, cockroachdb, postgres
const rawData = await repository.query(
    "SELECT * FROM USERS WHERE name = $1 and age = $2",
    ["John", 24],
)

// oracle
const rawData = await repository.query(
    "SELECT * FROM USERS WHERE name = :1 and age = :2",
    ["John", 24],
)

// spanner
const rawData = await repository.query(
    "SELECT * FROM USERS WHERE name = @param0 and age = @param1",
    ["John", 24],
)

// mssql
const rawData = await repository.query(
    "SELECT * FROM USERS WHERE name = @0 and age = @1",
    ["John", 24],
)

• clear - Очищает все данные из указанной таблицы (выполняет TRUNCATE/DROP).

await repository.clear()

Дополнительные опции

Для метода save можно передать необязательный параметр SaveOptions.

• data - Дополнительные данные для передачи в метод сохранения. Могут использоваться в подписчиках.

• listeners: boolean - Определяет, вызывать ли слушатели и подписчики для операции. По умолчанию включено; отключите через { listeners: false } в опциях save/remove.

• transaction: boolean - По умолчанию транзакции включены, все запросы операции удаления выполняются в транзакции. Отключите через { transaction: false }.

• chunk: number - Разбивает сохранение на группы указанного размера. Например, для сохранения 100 000 объектов с проблемами, задайте { chunk: 10000 } для разбивки на группы по 10 000. Полезно при ограничениях драйвера на количество параметров.

• reload: boolean - Определяет, нужно ли перезагружать сущность во время сохранения. Работает только в СУБД без поддержки RETURNING/OUTPUT. Включено по умолчанию.

Пример:

userRepository.save(users, { chunk: 1000 })

Для методов remove и delete можно передать необязательный параметр RemoveOptions.

• data - Дополнительные данные для передачи в метод удаления. Могут использоваться в подписчиках.

• listeners: boolean - Определяет, вызывать ли слушатели и подписчики для операции. По умолчанию включено; отключите через { listeners: false } в опциях save/remove.

• transaction: boolean - По умолчанию транзакции включены, все запросы операции удаления выполняются в транзакции. Отключите через { transaction: false }.

• chunk: number - Разбивает удаление на группы указанного размера. Например, для удаления 100 000 объектов с проблемами, задайте { chunk: 10000 } для разбивки на группы по 10 000. Полезно при ограничениях драйвера на количество параметров.

Пример:

userRepository.remove(users, { chunk: 1000 })

API TreeRepository

Для API TreeRepository обратитесь к документации по древовидным сущностям.

API MongoRepository

Для API MongoRepository обратитесь к документации по MongoDB.