@lakutata/orm 0.0.0-stage → 3.0.0-beta.0

package/dist/cjs/components/Database.d.ts

@@ -0,0 +1,333 @@
+import { Component, Provider } from '@lakutata/core';
+import { type DataSourceOptions } from 'typeorm/data-source/DataSourceOptions.js';
+import { DataSource } from 'typeorm/data-source/DataSource.js';
+import { Driver } from 'typeorm/driver/Driver.js';
+import { EntityManager } from 'typeorm/entity-manager/EntityManager.js';
+import { NamingStrategyInterface } from 'typeorm/naming-strategy/NamingStrategyInterface.js';
+import { EntitySubscriberInterface } from 'typeorm/subscriber/EntitySubscriberInterface.js';
+import { EntityMetadata } from 'typeorm/metadata/EntityMetadata.js';
+import { EntityTarget } from 'typeorm/common/EntityTarget.js';
+import { Migration } from 'typeorm/migration/Migration.js';
+import { ObjectLiteral } from 'typeorm/common/ObjectLiteral.js';
+import { TreeRepository } from 'typeorm/repository/TreeRepository.js';
+import { Repository } from 'typeorm/repository/Repository.js';
+import { MongoRepository } from 'typeorm/repository/MongoRepository.js';
+import { QueryRunner } from 'typeorm/query-runner/QueryRunner.js';
+import { SelectQueryBuilder } from 'typeorm/query-builder/SelectQueryBuilder.js';
+import { ReplicationMode } from 'typeorm/driver/types/ReplicationMode.js';
+import { QueryResultCache } from 'typeorm/cache/QueryResultCache.js';
+import { IsolationLevel } from 'typeorm/driver/types/IsolationLevel.js';
+import { type MigrationRunOptions } from '../types/MigrationRunOptions.js';
+/**
+ * Build the registration of a {@link Database} component, for the `components` of the application options: the
+ * component class with its TypeORM connection options.
+ * @param options The TypeORM connection options (`DataSourceOptions`): the driver `type`, the connection settings, the
+ * `entities`, the `migrations`, `synchronize`, `migrationsRun`, `logging`… Passed to TypeORM as they are.
+ * @returns The registration `{class: Database, options}`.
+ * @example
+ * ```typescript
+ * import {Application} from 'lakutata'
+ * import {buildDatabaseOptions} from 'lakutata/com/database'
+ * import {Column, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+ *
+ * @Entity()
+ * class User {
+ *     @PrimaryGeneratedColumn()
+ *     public id: number
+ *
+ *     @Column()
+ *     public name: string
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'com.example.app',
+ *     name: 'Example',
+ *     components: {
+ *         //A PostgreSQL connection (the pg package installed), the component named db
+ *         db: buildDatabaseOptions({
+ *             type: 'postgres',
+ *             host: 'localhost',
+ *             port: 5432,
+ *             username: 'postgres',
+ *             password: 'secret',
+ *             database: 'example',
+ *             entities: [User]
+ *         })
+ *     },
+ *     //Connected while the application launches: a connection failure stops it
+ *     bootstrap: ['db']
+ * }))
+ * ```
+ */
+export declare const buildDatabaseOptions: (options: DataSourceOptions) => {
+    class: typeof Database;
+    options: DataSourceOptions;
+};
+/**
+ * A database connection shared by the whole application: a singleton component wrapping a TypeORM `DataSource`.
+ *
+ * Register it in the `components` of the application options with {@link buildDatabaseOptions}, then inject it by its
+ * name (`@Inject('db')`) or get it with `getObject('db')`. It connects when it is created (while the application
+ * launches when it is listed in `bootstrap`, otherwise on its first use): a connection failure rejects its creation
+ * with the driver error. TypeORM applies `synchronize` and `migrationsRun` of the options while connecting. It
+ * disconnects when the application stops.
+ *
+ * An application may register several of them (one per database), each under its own name. Their names are the ones
+ * the migration commands of the application (`MIGRATION_GENERATE`, `MIGRATION_RUN`…) select with `MIGRATION_DATABASE`.
+ * @example
+ * ```typescript
+ * import {Application, Component} from 'lakutata'
+ * import {Inject} from 'lakutata/decorator/di'
+ * import {buildDatabaseOptions, Database} from 'lakutata/com/database'
+ * import {Column, Entity, PrimaryGeneratedColumn} from 'lakutata/decorator/orm'
+ *
+ * @Entity()
+ * class Account {
+ *     @PrimaryGeneratedColumn()
+ *     public id: number
+ *
+ *     @Column('integer', {default: 0})
+ *     public balance: number
+ * }
+ *
+ * class Bank extends Component {
+ *     @Inject('db')
+ *     protected readonly db: Database
+ *
+ *     public async balance(id: number): Promise<number> {
+ *         const account: Account | null = await this.db.getRepository(Account).findOneBy({id: id})
+ *         return account ? account.balance : 0
+ *     }
+ *
+ *     //Both updates are committed, or none when one fails
+ *     public async transfer(from: number, to: number, amount: number): Promise<void> {
+ *         await this.db.transaction(async (manager): Promise<void> => {
+ *             await manager.decrement(Account, {id: from}, 'balance', amount)
+ *             await manager.increment(Account, {id: to}, 'balance', amount)
+ *         })
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'com.example.bank',
+ *     name: 'Bank',
+ *     components: {
+ *         db: buildDatabaseOptions({type: 'postgres', url: 'postgres://postgres:secret@localhost:5432/bank', entities: [Account]}),
+ *         bank: {class: Bank}
+ *     },
+ *     bootstrap: ['db']
+ * }))
+ * ```
+ */
+export declare class Database extends Component {
+    #private;
+    /**
+     * Load the provider generating the migrations of the database. The application calls it when it is started with
+     * `MIGRATION_GENERATE`: the applications do not call it.
+     * @returns The migration generator provider class.
+     */
+    static migrationGenerator: () => Promise<typeof Provider>;
+    /**
+     * Load the provider running, reverting or showing the migrations of the database. The application calls it when it
+     * is started with `MIGRATION_RUN`, `MIGRATION_REVERT` or `MIGRATION_SHOW`: the applications do not call it.
+     * @returns The migration executor provider class.
+     */
+    static migrationExecutor: () => Promise<typeof Provider>;
+    /**
+     * The TypeORM connection options, given by the registration (see {@link buildDatabaseOptions}). Not validated by
+     * lakutata: TypeORM checks them while connecting.
+     */
+    protected readonly options: DataSourceOptions;
+    /**
+     * The TypeORM `DataSource` of the connection, for the subclasses needing what this class does not expose.
+     */
+    protected get datasource(): DataSource;
+    /**
+     * The TypeORM driver of the connection (PostgreSQL, MySQL, SQLite…).
+     */
+    get driver(): Driver;
+    /**
+     * The entity manager of the connection: the TypeORM operations on any entity (`find`, `save`, `delete`…) outside a
+     * transaction.
+     */
+    get manager(): EntityManager;
+    /**
+     * Replace the naming strategy of the connection, which names the tables, the columns and the constraints of the
+     * entities. Set it before the metadata is used: the names already built are not renamed.
+     * @param instance The naming strategy.
+     */
+    set namingStrategy(instance: NamingStrategyInterface);
+    /**
+     * The naming strategy of the connection, which names the tables, the columns and the constraints of the entities.
+     * @default TypeORM's `DefaultNamingStrategy`, unless the options set `namingStrategy`
+     */
+    get namingStrategy(): NamingStrategyInterface;
+    /**
+     * The entity subscribers registered on the connection (the `subscribers` of the options).
+     */
+    get subscribers(): EntitySubscriberInterface<any>[];
+    /**
+     * The metadata of every entity registered on the connection.
+     */
+    get entityMetadatas(): EntityMetadata[];
+    /**
+     * The metadata of every entity registered on the connection, by entity target (class, name or schema): the same as
+     * {@link Database.entityMetadatas}, for fast lookups.
+     */
+    get entityMetadatasMap(): Map<EntityTarget<any>, EntityMetadata>;
+    /**
+     * The query result cache of the connection, `undefined` unless the options enable `cache`.
+     */
+    get queryResultCache(): QueryResultCache | undefined;
+    /**
+     * Connect to the database with the options.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Disconnect from the database.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Create or update the database schema from the registered entities (the tables, columns, indices and foreign
+     * keys). Meant for development: the migrations change the schema of a production database.
+     * @param dropBeforeSync Drop every table of the database schema, with its data (also the tables of no entity),
+     * before creating the schema. Defaults to `false`.
+     * @returns Resolves once the schema is built.
+     * @throws {CannotExecuteNotConnectedError} When the connection is closed.
+     */
+    synchronize(dropBeforeSync?: boolean): Promise<void>;
+    /**
+     * Run the pending migrations (the `migrations` of the options not yet recorded in the migrations table), in their
+     * timestamp order.
+     * @param options The transactions of the migrations, and whether they are only recorded (`fake`).
+     * @returns The migrations run, an empty array when none is pending.
+     * @throws {CannotExecuteNotConnectedError} When the connection is closed.
+     * @throws {Error} The error of a failed migration, once its transaction (`'all'` or `'each'`) is rolled back.
+     */
+    runMigrations(options?: MigrationRunOptions): Promise<Migration[]>;
+    /**
+     * Revert the last migration run (its `down()`), and remove it from the migrations table. Does nothing when no
+     * migration was run.
+     * @param options The transaction of the migration (`'all'` by default, `migrationsTransactionMode` not applying),
+     * and whether it is only removed from the migrations table (`fake`).
+     * @returns Resolves once the migration is reverted.
+     * @throws {CannotExecuteNotConnectedError} When the connection is closed.
+     */
+    undoLastMigration(options?: MigrationRunOptions): Promise<void>;
+    /**
+     * Log each migration of the options with whether it was run (`[X]`) or not (`[ ]`), through the logger of the
+     * connection (shown when its `logging` includes `schema`).
+     * @returns Whether a migration is pending.
+     */
+    showMigrations(): Promise<boolean>;
+    /**
+     * Whether an entity is registered on the connection.
+     * @param target The entity class, its name, or its table name.
+     * @returns `true` when the connection has its metadata.
+     */
+    hasMetadata(target: EntityTarget<any>): boolean;
+    /**
+     * The metadata of a registered entity: its table, columns, relations…
+     * @param target The entity class, its name, or its table name.
+     * @returns The metadata of the entity.
+     * @throws {EntityMetadataNotFoundError} When the entity is not registered on the connection.
+     */
+    getMetadata(target: EntityTarget<any>): EntityMetadata;
+    /**
+     * The repository of an entity, created once per entity: its `find`, `save`, `delete`… operations outside a
+     * transaction (in a transaction, use the entity manager given to the callback).
+     * @param target The entity class, its name, or its `EntitySchema`.
+     * @returns The repository of the entity (a `MongoRepository` on a MongoDB connection).
+     * @throws {EntityMetadataNotFoundError} From the repository operations, when the entity is not registered.
+     */
+    getRepository<Entity extends ObjectLiteral>(target: EntityTarget<Entity>): Repository<Entity>;
+    /**
+     * The tree repository of an entity decorated with `@Tree()`: the operations on its ancestors and descendants
+     * (`findTrees`, `findDescendants`…).
+     * @param target The tree entity class, or its name.
+     * @returns The tree repository of the entity.
+     * @throws {TreeRepositoryNotSupportedError} On a driver without tree support (MongoDB).
+     */
+    getTreeRepository<Entity extends ObjectLiteral>(target: EntityTarget<Entity>): TreeRepository<Entity>;
+    /**
+     * The MongoDB repository of an entity: the repository operations plus the MongoDB ones (`aggregate`, `bulkWrite`…).
+     * @param target The entity class, or its name.
+     * @returns The MongoDB repository of the entity.
+     * @throws {TypeORMError} When the connection is not a MongoDB one.
+     */
+    getMongoRepository<Entity extends ObjectLiteral>(target: EntityTarget<Entity>): MongoRepository<Entity>;
+    /**
+     * Run a function in a transaction, on one connection of the pool: committed when the function resolves, rolled
+     * back when it rejects (its error rethrown). Every operation of the transaction goes through the entity manager given
+     * to the function: the ones made through {@link Database.manager} or the repositories of this object run outside of
+     * it.
+     * @param runInTransaction The function, given the entity manager of the transaction.
+     * @returns What the function resolves.
+     * @throws {Error} The error of the function, or of the database, after the rollback.
+     */
+    transaction<T>(runInTransaction: (entityManager: EntityManager) => Promise<T>): Promise<T>;
+    /**
+     * Run a function in a transaction with an isolation level, on one connection of the pool: committed when the
+     * function resolves, rolled back when it rejects (its error rethrown). Every operation of the transaction goes
+     * through the entity manager given to the function.
+     * @param isolationLevel The isolation level: `'READ UNCOMMITTED'`, `'READ COMMITTED'`, `'REPEATABLE READ'` or
+     * `'SERIALIZABLE'` (the levels the driver supports).
+     * @param runInTransaction The function, given the entity manager of the transaction.
+     * @returns What the function resolves.
+     * @throws {Error} The error of the function, or of the database, after the rollback.
+     */
+    transaction<T>(isolationLevel: IsolationLevel, runInTransaction: (entityManager: EntityManager) => Promise<T>): Promise<T>;
+    /**
+     * Run a raw SQL query.
+     * @param query The SQL, its parameters as placeholders: `$1`, `$2`… for PostgreSQL, `?` for MySQL and SQLite.
+     * @param parameters The values of the placeholders, escaped by the driver.
+     * @param queryRunner The query runner to run it on (a transaction of {@link Database.createQueryRunner}), a
+     * connection of the pool otherwise.
+     * @returns The raw result of the driver: the rows of a `SELECT` (an array of objects).
+     * @throws {QueryFailedError} When the database rejects the query.
+     */
+    query<T = any>(query: string, parameters?: any[], queryRunner?: QueryRunner): Promise<T>;
+    /**
+     * Create a query builder selecting an entity.
+     * @param entityClass The entity class, its name, or its `EntitySchema`.
+     * @param alias The alias of the entity in the query (`'user'` in `user.name`).
+     * @param queryRunner The query runner to run the query on, a connection of the pool otherwise.
+     * @returns The query builder, selecting the entity from its table.
+     * @throws {EntityMetadataNotFoundError} When the entity is not registered.
+     * @throws {TypeORMError} On a MongoDB connection, which has no query builder.
+     */
+    createQueryBuilder<Entity extends ObjectLiteral>(entityClass: EntityTarget<Entity>, alias: string, queryRunner?: QueryRunner): SelectQueryBuilder<Entity>;
+    /**
+     * Create an empty query builder, its selection and source set by its `select()` and `from()`.
+     * @param queryRunner The query runner to run the query on, a connection of the pool otherwise.
+     * @returns The query builder.
+     * @throws {TypeORMError} On a MongoDB connection, which has no query builder.
+     */
+    createQueryBuilder(queryRunner?: QueryRunner): SelectQueryBuilder<any>;
+    /**
+     * Create a query runner: one connection taken from the pool, to run several queries on the same connection and
+     * control its transaction by hand (`connect()`, `startTransaction()`, `commitTransaction()`,
+     * `rollbackTransaction()`). The caller must `release()` it, or the connection stays taken.
+     * @param mode With replication, `'master'` (the default) for the writes, `'slave'` for the reads on a replica.
+     * @returns The query runner, not connected until its first query or `connect()`.
+     */
+    createQueryRunner(mode?: ReplicationMode): QueryRunner;
+    /**
+     * The metadata of the junction table of a many-to-many relation.
+     * @param entityTarget The entity owning the relation.
+     * @param relationPropertyPath The property of the relation (`'tags'`, or a path such as `'profile.tags'`).
+     * @returns The metadata of the junction table.
+     * @throws {EntityMetadataNotFoundError} When the entity is not registered.
+     * @throws {TypeORMError} When the entity has no such relation, or the relation is not a many-to-many one.
+     */
+    getManyToManyMetadata(entityTarget: EntityTarget<any>, relationPropertyPath: string): EntityMetadata | undefined;
+    /**
+     * Create an entity manager on the connection, bound to a query runner when given (its operations then run on the
+     * runner's connection and transaction).
+     * @param queryRunner The query runner the manager uses, a connection of the pool per operation otherwise.
+     * @returns The entity manager.
+     */
+    createEntityManager(queryRunner?: QueryRunner): EntityManager;
+}