@deenruv/core 1.0.0

package/dist/connection/transaction-wrapper.d.ts

@@ -0,0 +1,33 @@
+import { Observable } from "rxjs";
+import { Connection } from "typeorm";
+import { RequestContext } from "../api/common/request-context";
+import { TransactionIsolationLevel, TransactionMode } from "../api/decorators/transaction.decorator";
+/**
+ * @description
+ * This helper class is used to wrap operations in a TypeORM transaction in order to ensure
+ * atomic operations on the database.
+ */
+export declare class TransactionWrapper {
+    /**
+     * @description
+     * Executes the `work` function within the context of a transaction. If the `work` function
+     * resolves / completes, then all the DB operations it contains will be committed. If it
+     * throws an error or rejects, then all DB operations will be rolled back.
+     *
+     * @note
+     * This function does not mutate your context. Instead, this function makes a copy and passes
+     * context to work function.
+     */
+    executeInTransaction<T>(originalCtx: RequestContext, work: (ctx: RequestContext) => Observable<T> | Promise<T>, mode: TransactionMode, isolationLevel: TransactionIsolationLevel | undefined, connection: Connection): Promise<T>;
+    /**
+     * Attempts to start a DB transaction, with retry logic in the case that a transaction
+     * is already started for the connection (which is mainly a problem with SQLite/Sql.js)
+     */
+    private startTransaction;
+    /**
+     * If the resolver function throws an error, there are certain cases in which
+     * we want to retry the whole thing again - notably in the case of a deadlock
+     * situation, which can usually be retried with success.
+     */
+    private isRetriableError;
+}

package/dist/connection/transaction-wrapper.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionWrapper = void 0;
+const rxjs_1 = require("rxjs");
+const operators_1 = require("rxjs/operators");
+const TransactionAlreadyStartedError_1 = require("typeorm/error/TransactionAlreadyStartedError");
+const constants_1 = require("../common/constants");
+/**
+ * @description
+ * This helper class is used to wrap operations in a TypeORM transaction in order to ensure
+ * atomic operations on the database.
+ */
+class TransactionWrapper {
+    /**
+     * @description
+     * Executes the `work` function within the context of a transaction. If the `work` function
+     * resolves / completes, then all the DB operations it contains will be committed. If it
+     * throws an error or rejects, then all DB operations will be rolled back.
+     *
+     * @note
+     * This function does not mutate your context. Instead, this function makes a copy and passes
+     * context to work function.
+     */
+    async executeInTransaction(originalCtx, work, mode, isolationLevel, connection) {
+        // Copy to make sure original context will remain valid after transaction completes
+        const ctx = originalCtx.copy();
+        const entityManager = ctx[constants_1.TRANSACTION_MANAGER_KEY];
+        const queryRunner = (entityManager === null || entityManager === void 0 ? void 0 : entityManager.queryRunner) || connection.createQueryRunner();
+        if (mode === "auto") {
+            await this.startTransaction(queryRunner, isolationLevel);
+        }
+        ctx[constants_1.TRANSACTION_MANAGER_KEY] = queryRunner.manager;
+        try {
+            const maxRetries = 5;
+            const result = await (0, rxjs_1.lastValueFrom)((0, rxjs_1.from)(work(ctx)).pipe((0, operators_1.retryWhen)((errors) => errors.pipe((0, operators_1.tap)((err) => {
+                if (!this.isRetriableError(err)) {
+                    throw err;
+                }
+            }), (0, operators_1.take)(maxRetries)))));
+            if (queryRunner.isTransactionActive) {
+                await queryRunner.commitTransaction();
+            }
+            return result;
+        }
+        catch (error) {
+            if (queryRunner.isTransactionActive) {
+                await queryRunner.rollbackTransaction();
+            }
+            throw error;
+        }
+        finally {
+            if (!queryRunner.isTransactionActive &&
+                queryRunner.isReleased === false) {
+                // There is a check for an active transaction
+                // because this could be a nested transaction (savepoint).
+                await queryRunner.release();
+            }
+        }
+    }
+    /**
+     * Attempts to start a DB transaction, with retry logic in the case that a transaction
+     * is already started for the connection (which is mainly a problem with SQLite/Sql.js)
+     */
+    async startTransaction(queryRunner, isolationLevel) {
+        const maxRetries = 25;
+        let attempts = 0;
+        let lastError;
+        // Returns false if a transaction is already in progress
+        async function attemptStartTransaction() {
+            try {
+                await queryRunner.startTransaction(isolationLevel);
+                return true;
+            }
+            catch (err) {
+                lastError = err;
+                if (err instanceof TransactionAlreadyStartedError_1.TransactionAlreadyStartedError) {
+                    return false;
+                }
+                throw err;
+            }
+        }
+        while (attempts < maxRetries) {
+            const result = await attemptStartTransaction();
+            if (result) {
+                return;
+            }
+            attempts++;
+            // insert an increasing delay before retrying
+            await new Promise((resolve) => setTimeout(resolve, attempts * 20));
+        }
+        throw lastError;
+    }
+    /**
+     * If the resolver function throws an error, there are certain cases in which
+     * we want to retry the whole thing again - notably in the case of a deadlock
+     * situation, which can usually be retried with success.
+     */
+    isRetriableError(err) {
+        const mysqlDeadlock = err.code === "ER_LOCK_DEADLOCK";
+        const postgresDeadlock = err.code === "deadlock_detected";
+        return mysqlDeadlock || postgresDeadlock;
+    }
+}
+exports.TransactionWrapper = TransactionWrapper;
+//# sourceMappingURL=transaction-wrapper.js.map

package/dist/connection/transaction-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-wrapper.js","sourceRoot":"","sources":["../../src/connection/transaction-wrapper.ts"],"names":[],"mappings":"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"}

package/dist/connection/transactional-connection.d.ts

@@ -0,0 +1,132 @@
+import { ID, Type } from "@deenruv/common/lib/shared-types";
+import { DataSource, EntitySchema, FindManyOptions, FindOneOptions, ObjectLiteral, ObjectType, Repository } from "typeorm";
+import { RequestContext } from "../api/common/request-context";
+import { TransactionIsolationLevel } from "../api/decorators/transaction.decorator";
+import { ChannelAware } from "../common/types/common-types";
+import { DeenruvEntity } from "../entity/base/base.entity";
+import { TransactionWrapper } from "./transaction-wrapper";
+import { GetEntityOrThrowOptions } from "./types";
+/**
+ * @description
+ * The TransactionalConnection is a wrapper around the TypeORM `Connection` object which works in conjunction
+ * with the {@link Transaction} decorator to implement per-request transactions. All services which access the
+ * database should use this class rather than the raw TypeORM connection, to ensure that db changes can be
+ * easily wrapped in transactions when required.
+ *
+ * The service layer does not need to know about the scope of a transaction, as this is covered at the
+ * API by the use of the `Transaction` decorator.
+ *
+ * @docsCategory data-access
+ */
+export declare class TransactionalConnection {
+    private dataSource;
+    private transactionWrapper;
+    constructor(dataSource: DataSource, transactionWrapper: TransactionWrapper);
+    /**
+     * @description
+     * The plain TypeORM Connection object. Should be used carefully as any operations
+     * performed with this connection will not be performed within any outer
+     * transactions.
+     */
+    get rawConnection(): DataSource;
+    /**
+     * @description
+     * Returns a TypeORM repository. Note that when no RequestContext is supplied, the repository will not
+     * be aware of any existing transaction. Therefore, calling this method without supplying a RequestContext
+     * is discouraged without a deliberate reason.
+     *
+     * @deprecated since 1.7.0: Use {@link TransactionalConnection.rawConnection rawConnection.getRepository()} function instead.
+     */
+    getRepository<Entity extends ObjectLiteral>(target: ObjectType<Entity> | EntitySchema<Entity> | string): Repository<Entity>;
+    /**
+     * @description
+     * Returns a TypeORM repository which is bound to any existing transactions. It is recommended to _always_ pass
+     * the RequestContext argument when possible, otherwise the queries will be executed outside of any
+     * ongoing transactions which have been started by the {@link Transaction} decorator.
+     */
+    getRepository<Entity extends ObjectLiteral>(ctx: RequestContext | undefined, target: ObjectType<Entity> | EntitySchema<Entity> | string): Repository<Entity>;
+    /**
+     * @description
+     * Allows database operations to be wrapped in a transaction, ensuring that in the event of an error being
+     * thrown at any point, the entire transaction will be rolled back and no changes will be saved.
+     *
+     * In the context of API requests, you should instead use the {@link Transaction} decorator on your resolver or
+     * controller method.
+     *
+     * On the other hand, for code that does not run in the context of a GraphQL/REST request, this method
+     * should be used to protect against non-atomic changes to the data which could leave your data in an
+     * inconsistent state.
+     *
+     * Such situations include function processed by the JobQueue or stand-alone scripts which make use
+     * of Deenruv internal services.
+     *
+     * If there is already a {@link RequestContext} object available, you should pass it in as the first
+     * argument in order to create transactional context as the copy. If not, omit the first argument and an empty
+     * RequestContext object will be created, which is then used to propagate the transaction to
+     * all inner method calls.
+     *
+     * @example
+     * ```ts
+     * private async transferCredit(outerCtx: RequestContext, fromId: ID, toId: ID, amount: number) {
+     *   await this.connection.withTransaction(outerCtx, async ctx => {
+     *     // Note you must not use `outerCtx` here, instead use `ctx`. Otherwise, this query
+     *     // will be executed outside of transaction
+     *     await this.giftCardService.updateCustomerCredit(ctx, fromId, -amount);
+     *
+     *     await this.connection.getRepository(ctx, GiftCard).update(fromId, { transferred: true })
+     *
+     *     // If some intermediate logic here throws an Error,
+     *     // then all DB transactions will be rolled back and neither Customer's
+     *     // credit balance will have changed.
+     *
+     *     await this.giftCardService.updateCustomerCredit(ctx, toId, amount);
+     *   })
+     * }
+     * ```
+     *
+     * @since 1.3.0
+     */
+    withTransaction<T>(work: (ctx: RequestContext) => Promise<T>): Promise<T>;
+    withTransaction<T>(ctx: RequestContext, work: (ctx: RequestContext) => Promise<T>): Promise<T>;
+    /**
+     * @description
+     * Manually start a transaction if one is not already in progress. This method should be used in
+     * conjunction with the `'manual'` mode of the {@link Transaction} decorator.
+     */
+    startTransaction(ctx: RequestContext, isolationLevel?: TransactionIsolationLevel): Promise<void>;
+    /**
+     * @description
+     * Manually commits any open transaction. Should be very rarely needed, since the {@link Transaction} decorator
+     * and the internal TransactionInterceptor take care of this automatically. Use-cases include situations
+     * in which the worker thread needs to access changes made in the current transaction, or when using the
+     * Transaction decorator in manual mode.
+     */
+    commitOpenTransaction(ctx: RequestContext): Promise<void>;
+    /**
+     * @description
+     * Manually rolls back any open transaction. Should be very rarely needed, since the {@link Transaction} decorator
+     * and the internal TransactionInterceptor take care of this automatically. Use-cases include when using the
+     * Transaction decorator in manual mode.
+     */
+    rollBackTransaction(ctx: RequestContext): Promise<void>;
+    /**
+     * @description
+     * Finds an entity of the given type by ID, or throws an `EntityNotFoundError` if none
+     * is found.
+     */
+    getEntityOrThrow<T extends DeenruvEntity>(ctx: RequestContext, entityType: Type<T>, id: ID, options?: GetEntityOrThrowOptions<T>): Promise<T>;
+    private getEntityOrThrowInternal;
+    /**
+     * @description
+     * Like the TypeOrm `Repository.findOne()` method, but limits the results to
+     * the given Channel.
+     */
+    findOneInChannel<T extends ChannelAware & DeenruvEntity>(ctx: RequestContext, entity: Type<T>, id: ID, channelId: ID, options?: FindOneOptions<T>): Promise<T | undefined>;
+    /**
+     * @description
+     * Like the TypeOrm `Repository.findByIds()` method, but limits the results to
+     * the given Channel.
+     */
+    findByIdsInChannel<T extends ChannelAware | DeenruvEntity>(ctx: RequestContext, entity: Type<T>, ids: ID[], channelId: ID, options: FindManyOptions<T>): Promise<T[]>;
+    private getTransactionManager;
+}

package/dist/connection/transactional-connection.js

@@ -0,0 +1,234 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionalConnection = void 0;
+const common_1 = require("@nestjs/common");
+const typeorm_decorators_1 = require("@nestjs/typeorm/dist/common/typeorm.decorators");
+const typeorm_1 = require("typeorm");
+const request_context_1 = require("../api/common/request-context");
+const constants_1 = require("../common/constants");
+const errors_1 = require("../common/error/errors");
+const tree_relations_qb_joiner_1 = require("../service/helpers/utils/tree-relations-qb-joiner");
+const find_options_object_to_array_1 = require("./find-options-object-to-array");
+const transaction_wrapper_1 = require("./transaction-wrapper");
+/**
+ * @description
+ * The TransactionalConnection is a wrapper around the TypeORM `Connection` object which works in conjunction
+ * with the {@link Transaction} decorator to implement per-request transactions. All services which access the
+ * database should use this class rather than the raw TypeORM connection, to ensure that db changes can be
+ * easily wrapped in transactions when required.
+ *
+ * The service layer does not need to know about the scope of a transaction, as this is covered at the
+ * API by the use of the `Transaction` decorator.
+ *
+ * @docsCategory data-access
+ */
+let TransactionalConnection = class TransactionalConnection {
+    constructor(dataSource, transactionWrapper) {
+        this.dataSource = dataSource;
+        this.transactionWrapper = transactionWrapper;
+    }
+    /**
+     * @description
+     * The plain TypeORM Connection object. Should be used carefully as any operations
+     * performed with this connection will not be performed within any outer
+     * transactions.
+     */
+    get rawConnection() {
+        return this.dataSource;
+    }
+    getRepository(ctxOrTarget, maybeTarget) {
+        if (ctxOrTarget instanceof request_context_1.RequestContext) {
+            const transactionManager = this.getTransactionManager(ctxOrTarget);
+            if (transactionManager) {
+                return transactionManager.getRepository(maybeTarget);
+            }
+            else {
+                return this.rawConnection.getRepository(maybeTarget);
+            }
+        }
+        else {
+            return this.rawConnection.getRepository(ctxOrTarget !== null && ctxOrTarget !== void 0 ? ctxOrTarget : maybeTarget);
+        }
+    }
+    async withTransaction(ctxOrWork, maybeWork) {
+        let ctx;
+        let work;
+        if (ctxOrWork instanceof request_context_1.RequestContext) {
+            ctx = ctxOrWork;
+            work = maybeWork;
+        }
+        else {
+            ctx = request_context_1.RequestContext.empty();
+            work = ctxOrWork;
+        }
+        return this.transactionWrapper.executeInTransaction(ctx, work, "auto", undefined, this.rawConnection);
+    }
+    /**
+     * @description
+     * Manually start a transaction if one is not already in progress. This method should be used in
+     * conjunction with the `'manual'` mode of the {@link Transaction} decorator.
+     */
+    async startTransaction(ctx, isolationLevel) {
+        var _a;
+        const transactionManager = this.getTransactionManager(ctx);
+        if (((_a = transactionManager === null || transactionManager === void 0 ? void 0 : transactionManager.queryRunner) === null || _a === void 0 ? void 0 : _a.isTransactionActive) === false) {
+            await transactionManager.queryRunner.startTransaction(isolationLevel);
+        }
+    }
+    /**
+     * @description
+     * Manually commits any open transaction. Should be very rarely needed, since the {@link Transaction} decorator
+     * and the internal TransactionInterceptor take care of this automatically. Use-cases include situations
+     * in which the worker thread needs to access changes made in the current transaction, or when using the
+     * Transaction decorator in manual mode.
+     */
+    async commitOpenTransaction(ctx) {
+        var _a;
+        const transactionManager = this.getTransactionManager(ctx);
+        if ((_a = transactionManager === null || transactionManager === void 0 ? void 0 : transactionManager.queryRunner) === null || _a === void 0 ? void 0 : _a.isTransactionActive) {
+            await transactionManager.queryRunner.commitTransaction();
+        }
+    }
+    /**
+     * @description
+     * Manually rolls back any open transaction. Should be very rarely needed, since the {@link Transaction} decorator
+     * and the internal TransactionInterceptor take care of this automatically. Use-cases include when using the
+     * Transaction decorator in manual mode.
+     */
+    async rollBackTransaction(ctx) {
+        var _a;
+        const transactionManager = this.getTransactionManager(ctx);
+        if ((_a = transactionManager === null || transactionManager === void 0 ? void 0 : transactionManager.queryRunner) === null || _a === void 0 ? void 0 : _a.isTransactionActive) {
+            await transactionManager.queryRunner.rollbackTransaction();
+        }
+    }
+    /**
+     * @description
+     * Finds an entity of the given type by ID, or throws an `EntityNotFoundError` if none
+     * is found.
+     */
+    async getEntityOrThrow(ctx, entityType, id, options = {}) {
+        const { retries, retryDelay } = options;
+        if (retries == null || retries <= 0) {
+            return this.getEntityOrThrowInternal(ctx, entityType, id, options);
+        }
+        else {
+            let err;
+            const retriesInt = Math.ceil(retries);
+            const delay = Math.ceil(Math.max(retryDelay || 25, 1));
+            for (let attempt = 0; attempt < retriesInt; attempt++) {
+                try {
+                    const result = await this.getEntityOrThrowInternal(ctx, entityType, id, options);
+                    return result;
+                }
+                catch (e) {
+                    err = e;
+                    if (attempt < retriesInt - 1) {
+                        await new Promise((resolve) => setTimeout(resolve, delay));
+                    }
+                }
+            }
+            throw err;
+        }
+    }
+    async getEntityOrThrowInternal(ctx, entityType, id, options = {}) {
+        let entity;
+        if (options.channelId != null) {
+            const { channelId } = options, optionsWithoutChannelId = __rest(options, ["channelId"]);
+            entity = await this.findOneInChannel(ctx, entityType, id, options.channelId, optionsWithoutChannelId);
+        }
+        else {
+            const optionsWithId = Object.assign(Object.assign({}, options), { where: Object.assign(Object.assign({}, (options.where || {})), { id }) });
+            entity = await this.getRepository(ctx, entityType)
+                .findOne(optionsWithId)
+                .then((result) => result !== null && result !== void 0 ? result : undefined);
+        }
+        if (!entity ||
+            (entity.hasOwnProperty("deletedAt") &&
+                entity.deletedAt !== null &&
+                options.includeSoftDeleted !== true)) {
+            throw new errors_1.EntityNotFoundError(entityType.name, id);
+        }
+        return entity;
+    }
+    /**
+     * @description
+     * Like the TypeOrm `Repository.findOne()` method, but limits the results to
+     * the given Channel.
+     */
+    findOneInChannel(ctx, entity, id, channelId, options = {}) {
+        const qb = this.getRepository(ctx, entity).createQueryBuilder("entity");
+        if (options.relations) {
+            const joinedRelations = (0, tree_relations_qb_joiner_1.joinTreeRelationsDynamically)(qb, entity, options.relations);
+            // Remove any relations which are related to the 'collection' tree, as these are handled separately
+            // to avoid duplicate joins.
+            options.relations = (0, find_options_object_to_array_1.findOptionsObjectToArray)(options.relations).filter((relationPath) => !joinedRelations.has(relationPath));
+        }
+        qb.setFindOptions(Object.assign({ relationLoadStrategy: "query" }, options));
+        qb.leftJoin("entity.channels", "__channel")
+            .andWhere("entity.id = :id", { id })
+            .andWhere("__channel.id = :channelId", { channelId });
+        return qb.getOne().then((result) => {
+            return result !== null && result !== void 0 ? result : undefined;
+        });
+    }
+    /**
+     * @description
+     * Like the TypeOrm `Repository.findByIds()` method, but limits the results to
+     * the given Channel.
+     */
+    findByIdsInChannel(ctx, entity, ids, channelId, options) {
+        // the syntax described in https://github.com/typeorm/typeorm/issues/1239#issuecomment-366955628
+        // breaks if the array is empty
+        if (ids.length === 0) {
+            return Promise.resolve([]);
+        }
+        const qb = this.getRepository(ctx, entity).createQueryBuilder("entity");
+        if (Array.isArray(options.relations) && options.relations.length > 0) {
+            const joinedRelations = (0, tree_relations_qb_joiner_1.joinTreeRelationsDynamically)(qb, entity, options.relations);
+            // Remove any relations which are related to the 'collection' tree, as these are handled separately
+            // to avoid duplicate joins.
+            options.relations = options.relations.filter((relationPath) => !joinedRelations.has(relationPath));
+        }
+        qb.setFindOptions(Object.assign({ relationLoadStrategy: "query" }, options));
+        return qb
+            .leftJoin("entity.channels", "channel")
+            .andWhere("entity.id IN (:...ids)", { ids })
+            .andWhere("channel.id = :channelId", { channelId })
+            .getMany();
+    }
+    getTransactionManager(ctx) {
+        return ctx[constants_1.TRANSACTION_MANAGER_KEY];
+    }
+};
+exports.TransactionalConnection = TransactionalConnection;
+exports.TransactionalConnection = TransactionalConnection = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, typeorm_decorators_1.InjectDataSource)()),
+    __metadata("design:paramtypes", [typeorm_1.DataSource,
+        transaction_wrapper_1.TransactionWrapper])
+], TransactionalConnection);
+//# sourceMappingURL=transactional-connection.js.map

package/dist/connection/transactional-connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transactional-connection.js","sourceRoot":"","sources":["../../src/connection/transactional-connection.ts"],"names":[],"mappings":"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"}

package/dist/connection/types.d.ts

@@ -0,0 +1,42 @@
+import { ID } from "@deenruv/common/lib/shared-types";
+import { FindOneOptions } from "typeorm";
+/**
+ * @description
+ * Options used by the {@link TransactionalConnection} `getEntityOrThrow` method.
+ *
+ * @docsCategory data-access
+ */
+export interface GetEntityOrThrowOptions<T = any> extends FindOneOptions<T> {
+    /**
+     * @description
+     * An optional channelId to limit results to entities assigned to the given Channel. Should
+     * only be used when getting entities that implement the {@link ChannelAware} interface.
+     */
+    channelId?: ID;
+    /**
+     * @description
+     * If set to a positive integer, it will retry getting the entity in case it is initially not
+     * found.
+     *
+     * @since 1.1.0
+     * @default 0
+     */
+    retries?: number;
+    /**
+     * @description
+     * Specifies the delay in ms to wait between retries.
+     *
+     * @since 1.1.0
+     * @default 25
+     */
+    retryDelay?: number;
+    /**
+     * @description
+     * If set to `true`, soft-deleted entities will be returned. Otherwise they will
+     * throw as if they did not exist.
+     *
+     * @since 1.3.0
+     * @default false
+     */
+    includeSoftDeleted?: boolean;
+}

package/dist/connection/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/connection/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/connection/types.ts"],"names":[],"mappings":""}

package/dist/data-import/data-import.module.d.ts

@@ -0,0 +1,2 @@
+export declare class DataImportModule {
+}

package/dist/data-import/data-import.module.js

@@ -0,0 +1,50 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataImportModule = void 0;
+const common_1 = require("@nestjs/common");
+const config_module_1 = require("../config/config.module");
+const connection_module_1 = require("../connection/connection.module");
+const plugin_module_1 = require("../plugin/plugin.module");
+const service_module_1 = require("../service/service.module");
+const asset_importer_1 = require("./providers/asset-importer/asset-importer");
+const import_parser_1 = require("./providers/import-parser/import-parser");
+const fast_importer_service_1 = require("./providers/importer/fast-importer.service");
+const importer_1 = require("./providers/importer/importer");
+const populator_1 = require("./providers/populator/populator");
+let DataImportModule = class DataImportModule {
+};
+exports.DataImportModule = DataImportModule;
+exports.DataImportModule = DataImportModule = __decorate([
+    (0, common_1.Module)({
+        // Important! PluginModule must be defined before ServiceModule
+        // in order that overrides of Services (e.g. SearchService) are correctly
+        // registered with the injector.
+        imports: [
+            plugin_module_1.PluginModule.forRoot(),
+            service_module_1.ServiceModule,
+            connection_module_1.ConnectionModule.forPlugin(),
+            config_module_1.ConfigModule,
+        ],
+        exports: [
+            import_parser_1.ImportParser,
+            importer_1.Importer,
+            populator_1.Populator,
+            fast_importer_service_1.FastImporterService,
+            asset_importer_1.AssetImporter,
+        ],
+        providers: [
+            import_parser_1.ImportParser,
+            importer_1.Importer,
+            populator_1.Populator,
+            fast_importer_service_1.FastImporterService,
+            asset_importer_1.AssetImporter,
+        ],
+    })
+], DataImportModule);
+//# sourceMappingURL=data-import.module.js.map

package/dist/data-import/data-import.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-import.module.js","sourceRoot":"","sources":["../../src/data-import/data-import.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwC;AAExC,2DAAuD;AACvD,uEAAmE;AACnE,2DAAuD;AACvD,8DAA0D;AAE1D,8EAA0E;AAC1E,2EAAuE;AACvE,sFAAiF;AACjF,4DAAyD;AACzD,+DAA4D;AA2BrD,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;CAAG,CAAA;AAAnB,4CAAgB;2BAAhB,gBAAgB;IAzB5B,IAAA,eAAM,EAAC;QACN,+DAA+D;QAC/D,yEAAyE;QACzE,gCAAgC;QAChC,OAAO,EAAE;YACP,4BAAY,CAAC,OAAO,EAAE;YACtB,8BAAa;YACb,oCAAgB,CAAC,SAAS,EAAE;YAC5B,4BAAY;SACb;QACD,OAAO,EAAE;YACP,4BAAY;YACZ,mBAAQ;YACR,qBAAS;YACT,2CAAmB;YACnB,8BAAa;SACd;QACD,SAAS,EAAE;YACT,4BAAY;YACZ,mBAAQ;YACR,qBAAS;YACT,2CAAmB;YACnB,8BAAa;SACd;KACF,CAAC;GACW,gBAAgB,CAAG"}

package/dist/data-import/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./providers/populator/populator";
+export * from "./providers/importer/importer";
+export * from "./providers/importer/fast-importer.service";
+export * from "./providers/asset-importer/asset-importer";
+export * from "./providers/import-parser/import-parser";
+export * from "./types";