@tsed/mikro-orm 8.0.1 → 8.0.3

package/src/filters/OptimisticLockErrorFilter.ts

@@ -0,0 +1,19 @@
+import {OptimisticLockError} from "@mikro-orm/core";
+import {Catch, type ExceptionFilterMethods} from "@tsed/platform-exceptions";
+import {PlatformContext} from "@tsed/platform-http";
+
+@Catch(OptimisticLockError)
+export class OptimisticLockErrorFilter implements ExceptionFilterMethods<OptimisticLockError> {
+  public catch(exception: OptimisticLockError, ctx: PlatformContext): void {
+    const {response, logger} = ctx;
+
+    logger.error({
+      event: "MIKRO_ORM_OPTIMISTIC_LOCK_ERROR",
+      error_name: exception.name,
+      error_message: exception.message,
+      stack: exception.stack
+    });
+
+    response.status(409).body(`Update refused. The resource has changed on the server. Please try again later`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./constants.js";
+export * from "./decorators/entityManager.js";
+export * from "./decorators/orm.js";
+export * from "./decorators/subscriber.js";
+export * from "./decorators/transactional.js";
+export * from "./filters/OptimisticLockErrorFilter.js";
+export * from "./interceptors/TransactionalInterceptor.js";
+export * from "./interfaces/AfterTransactionCommit.js";
+export * from "./interfaces/BeforeTransactionCommit.js";
+export * from "./interfaces/RetryStrategy.js";
+export * from "./MikroOrmModule.js";
+export * from "./services/MikroOrmContext.js";
+export * from "./services/MikroOrmFactory.js";
+export * from "./services/MikroOrmRegistry.js";

package/src/interceptors/TransactionalInterceptor.spec.ts

@@ -0,0 +1,248 @@
+import {EntityManager, IsolationLevel, MikroORM, OptimisticLockError} from "@mikro-orm/core";
+import {InjectorService, InterceptorContext} from "@tsed/di";
+import {Logger} from "@tsed/logger";
+import {anyFunction, anything, deepEqual, instance, mock, objectContaining, reset, verify, when} from "ts-mockito";
+
+import {RetryStrategy} from "../interfaces/RetryStrategy.js";
+import {MikroOrmContext} from "../services/MikroOrmContext.js";
+import {MikroOrmRegistry} from "../services/MikroOrmRegistry.js";
+import {TransactionalInterceptor} from "./TransactionalInterceptor.js";
+
+// AHDOC: https://github.com/NagRock/ts-mockito/issues/191
+// TODO: avoid using ts-mockito
+const resolvableInstance = <T extends object>(m: T): T =>
+  new Proxy<T>(instance(m), {
+    get(target, prop, receiver) {
+      if (["Symbol(Symbol.toPrimitive)", "then", "catch"].includes(prop.toString())) {
+        return undefined;
+      }
+
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+
+describe("TransactionalInterceptor", () => {
+  const mockedInjectorService = mock<InjectorService>();
+  const mockedMikroOrmRegistry = mock<MikroOrmRegistry>();
+  const mockedMikroOrm = mock<MikroORM>();
+  const mockedEntityManager = mock<EntityManager>();
+  const mockedLogger = mock<Logger>();
+  const mockedRetryStrategy = mock<RetryStrategy>();
+  const mockedMikroOrmContext = mock<MikroOrmContext>();
+  const next = vi.fn();
+
+  let entityManger!: EntityManager;
+  let mikroOrm!: MikroORM;
+  let transactionalInterceptor!: TransactionalInterceptor;
+
+  afterEach(() => {
+    next.mockReset();
+    reset<InjectorService | MikroOrmRegistry | MikroORM | EntityManager | Logger | RetryStrategy | MikroOrmContext>(
+      mockedInjectorService,
+      mockedMikroOrmRegistry,
+      mockedMikroOrm,
+      mockedEntityManager,
+      mockedLogger,
+      mockedMikroOrmContext,
+      mockedRetryStrategy
+    );
+  });
+  beforeEach(() => {
+    entityManger = resolvableInstance(mockedEntityManager);
+    mikroOrm = resolvableInstance(mockedMikroOrm);
+    when(mockedMikroOrm.em).thenReturn(entityManger);
+
+    transactionalInterceptor = new TransactionalInterceptor(
+      instance(mockedInjectorService),
+      instance(mockedMikroOrmRegistry),
+      instance(mockedMikroOrmContext),
+      instance(mockedLogger)
+    );
+  });
+
+  describe("intercept", () => {
+    it("should run within a existing context", async () => {
+      // arrange
+      const context = {} as InterceptorContext;
+
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn(mikroOrm);
+      when(mockedMikroOrmContext.has(anything())).thenReturn(true);
+      when(mockedMikroOrmContext.get(anything())).thenReturn(entityManger);
+
+      // act
+      await transactionalInterceptor.intercept(context, next);
+
+      // assert
+      verify(mockedEntityManager.transactional(anyFunction(), objectContaining({}))).once();
+    });
+
+    it("should set an isolation level", async () => {
+      // arrange
+      const context = {options: {isolationLevel: IsolationLevel.SERIALIZABLE}} as InterceptorContext;
+
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn(mikroOrm);
+      when(mockedMikroOrmContext.has(anything())).thenReturn(true);
+      when(mockedMikroOrmContext.get(anything())).thenReturn(entityManger);
+
+      // act
+      await transactionalInterceptor.intercept(context, next);
+
+      // assert
+      verify(mockedEntityManager.transactional(anyFunction(), objectContaining({isolationLevel: IsolationLevel.SERIALIZABLE}))).once();
+    });
+
+    it("should run within a new context", async () => {
+      // arrange
+      const context = {} as InterceptorContext;
+
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn(mikroOrm);
+      when(mockedMikroOrmContext.has(anything())).thenReturn(false);
+      when(mockedMikroOrmContext.get(anything())).thenReturn(entityManger);
+      when(mockedMikroOrmContext.run(anything(), anything())).thenCall((_: EntityManager[], func: (...args: unknown[]) => unknown) =>
+        func()
+      );
+
+      // act
+      await transactionalInterceptor.intercept(context, next);
+
+      // assert
+      verify(mockedMikroOrmContext.run(deepEqual([entityManger]), anyFunction())).twice();
+      verify(mockedEntityManager.transactional(anyFunction(), objectContaining({}))).once();
+    });
+
+    it("should perform a task within a transaction", async () => {
+      // arrange
+      const context = {} as InterceptorContext;
+
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn(mikroOrm);
+      when(mockedMikroOrmContext.has(anything())).thenReturn(true);
+      when(mockedMikroOrmContext.get(anything())).thenReturn(entityManger);
+      when(mockedEntityManager.transactional(anything(), anything())).thenCall((func: (...args: unknown[]) => unknown) => func());
+
+      // act
+      await transactionalInterceptor.intercept(context, next);
+
+      // assert
+      expect(next).toHaveBeenCalled();
+    });
+
+    it("should emit events in the right order", async () => {
+      // arrange
+      const context = {} as InterceptorContext;
+
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn(mikroOrm);
+      when(mockedMikroOrmContext.has(anything())).thenReturn(true);
+      when(mockedMikroOrmContext.get(anything())).thenReturn(entityManger);
+      when(mockedEntityManager.transactional(anything(), anything())).thenCall((func: (...args: unknown[]) => unknown) => func());
+      when(mockedMikroOrmContext.run(anything(), anything())).thenCall((_: EntityManager[], func: (...args: unknown[]) => unknown) =>
+        func()
+      );
+
+      // act
+      await transactionalInterceptor.intercept(context, next);
+
+      // assert
+      verify(mockedInjectorService.alterAsync("$beforeTransactionCommit", entityManger)).calledBefore(
+        mockedInjectorService.alterAsync("$afterTransactionCommit", entityManger)
+      );
+    });
+
+    it("should disable an explicit transaction", async () => {
+      // arrange
+      const context = {options: {disabled: true}} as InterceptorContext;
+
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn(mikroOrm);
+      when(mockedMikroOrmContext.has(anything())).thenReturn(true);
+      when(mockedMikroOrmContext.get(anything())).thenReturn(entityManger);
+
+      // act
+      await transactionalInterceptor.intercept(context, next);
+
+      // assert
+      expect(next).toHaveBeenCalled();
+      verify(mockedEntityManager.transactional(anything(), anything())).never();
+    });
+
+    it("should throw an error if context is lost", async () => {
+      // arrange
+      const context = {} as InterceptorContext;
+
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn(mikroOrm);
+      when(mockedMikroOrmContext.has(anything())).thenReturn(true);
+      when(mockedEntityManager.transactional(anything(), anything())).thenCall((func: (...args: unknown[]) => unknown) => func());
+
+      // act
+      const result = transactionalInterceptor.intercept(context, next);
+
+      // assert
+      await expect(result).rejects.toThrow("No such context");
+    });
+
+    it("should throw an error if no such context", async () => {
+      // arrange
+      const context = {} as InterceptorContext;
+
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn();
+
+      // act
+      const result = transactionalInterceptor.intercept(context, next);
+
+      // assert
+      await expect(result).rejects.toThrow("No such context");
+    });
+
+    it("should throw an optimistic lock exception immediately if no retry strategy", async () => {
+      // arrange
+      const context = {} as InterceptorContext;
+
+      when(mockedMikroOrmContext.has(anything())).thenReturn(true);
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn(mikroOrm);
+      when(mockedEntityManager.transactional(anything(), anything())).thenReject(OptimisticLockError.lockFailed("Lock"));
+      when(mockedMikroOrmContext.get(anything())).thenReturn(entityManger);
+
+      // act
+      const result = transactionalInterceptor.intercept(context, next);
+
+      // assert
+      await expect(result).rejects.toThrow("Lock");
+      verify(mockedEntityManager.transactional(anyFunction(), objectContaining({}))).times(1);
+    });
+
+    it("should apply a retry mechanism if retry is enabled", async () => {
+      // arrange
+      transactionalInterceptor = new TransactionalInterceptor(
+        instance(mockedInjectorService),
+        instance(mockedMikroOrmRegistry),
+        instance(mockedMikroOrmContext),
+        instance(mockedLogger),
+        instance(mockedRetryStrategy)
+      );
+      const context = {options: {retry: true}} as InterceptorContext;
+
+      when(mockedMikroOrmContext.has(anything())).thenReturn(true);
+      when(mockedRetryStrategy.acquire(anything())).thenResolve();
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn(mikroOrm);
+      when(mockedEntityManager.transactional(anything(), anything())).thenReject(OptimisticLockError.lockFailed("Lock"));
+      when(mockedMikroOrmContext.get(anything())).thenReturn(entityManger);
+
+      // act
+      await transactionalInterceptor.intercept(context, next);
+
+      // assert
+      verify(mockedRetryStrategy.acquire(anything())).once();
+    });
+
+    it("should log a warning if the retry is enabled, while a retry strategy is not resolved", async () => {
+      // arrange
+      const context = {options: {retry: true}} as InterceptorContext;
+
+      when(mockedMikroOrmRegistry.get(anything())).thenReturn(instance(mockedMikroOrm));
+
+      // act
+      await transactionalInterceptor.intercept(context, next);
+
+      // assert
+      verify(mockedLogger.warn(`To retry a transaction you have to implement a "${RetryStrategy.description}" interface`)).once();
+    });
+  });
+});

package/src/interceptors/TransactionalInterceptor.ts

@@ -0,0 +1,130 @@
+import {EntityManager, FlushMode, IsolationLevel} from "@mikro-orm/core";
+import {Inject, InjectorService, Interceptor, InterceptorContext, InterceptorMethods, InterceptorNext} from "@tsed/di";
+import {Logger} from "@tsed/logger";
+
+import {DEFAULT_CONTEXT_NAME} from "../constants.js";
+import {RetryStrategy} from "../interfaces/RetryStrategy.js";
+import {MikroOrmContext} from "../services/MikroOrmContext.js";
+import {MikroOrmRegistry} from "../services/MikroOrmRegistry.js";
+
+export interface TransactionOptions {
+  retry?: boolean;
+  disabled?: boolean;
+  isolationLevel?: IsolationLevel;
+  flushMode?: FlushMode;
+  contextName?: string;
+}
+
+type TransactionSettings = Omit<TransactionOptions, "contextName"> & Required<Pick<TransactionOptions, "contextName">>;
+
+@Interceptor()
+export class TransactionalInterceptor implements InterceptorMethods {
+  constructor(
+    @Inject() private readonly injector: InjectorService,
+    @Inject() private readonly registry: MikroOrmRegistry,
+    @Inject() private readonly context: MikroOrmContext,
+    @Inject() private readonly logger: Logger,
+    @Inject(RetryStrategy)
+    private readonly retryStrategy?: RetryStrategy
+  ) {}
+
+  public intercept(context: InterceptorContext<unknown>, next: InterceptorNext) {
+    const options = this.extractContextName(context.options);
+
+    if (options.retry && !this.retryStrategy) {
+      this.logger.warn(`To retry a transaction you have to implement a "${RetryStrategy.description}" interface`);
+    }
+
+    return this.context.has(options.contextName) ? this.runWithinCtx(next, options) : this.runWithinNewCtx(next, options);
+  }
+
+  private runWithinCtx(next: InterceptorNext, options: TransactionSettings): Promise<unknown> {
+    const callback = () => this.executeInTransaction(next, options);
+
+    return options.retry && this.retryStrategy ? this.retryStrategy.acquire(callback) : callback();
+  }
+
+  private async runWithinNewCtx(next: InterceptorNext, options: TransactionSettings): Promise<unknown> {
+    const em = await this.getGlobalEntityManager(options.contextName);
+
+    return this.context.run([em], () => this.runWithinCtx(next, options));
+  }
+
+  private getGlobalEntityManager(contextName: string = DEFAULT_CONTEXT_NAME): EntityManager {
+    const orm = this.registry.get(contextName);
+
+    if (!orm) {
+      throw new Error(
+        `No such context: ${contextName}. Please register a corresponding MikroOrm instance using '@Configuration()' decorator.`
+      );
+    }
+
+    return orm.em;
+  }
+
+  private extractContextName(options: TransactionOptions | string | undefined): TransactionSettings {
+    if (typeof options === "string") {
+      return {
+        contextName: options
+      };
+    }
+
+    const {flushMode, isolationLevel, contextName = DEFAULT_CONTEXT_NAME, retry = false, disabled = false} = options ?? {};
+
+    return {
+      contextName,
+      retry,
+      disabled,
+      flushMode,
+      isolationLevel
+    };
+  }
+
+  private async executeInTransaction(next: InterceptorNext, options: TransactionSettings): Promise<unknown> {
+    const em = this.getEntityManager(options.contextName);
+
+    if (options.disabled) {
+      return next();
+    }
+
+    const result = await em.transactional(() => this.executeHandlerDelegate(next, options), {
+      flushMode: options.flushMode,
+      isolationLevel: options.isolationLevel
+    });
+
+    await this.afterTransactionCommit(options);
+
+    return result;
+  }
+
+  private async executeHandlerDelegate(next: InterceptorNext, options: TransactionSettings): Promise<unknown> {
+    const result = await next();
+    await this.beforeTransactionCommit(options);
+    return result;
+  }
+
+  private beforeTransactionCommit(options: TransactionSettings): Promise<unknown> {
+    return this.injector.alterAsync("$beforeTransactionCommit", this.getEntityManager(options.contextName));
+  }
+
+  private afterTransactionCommit(options: TransactionSettings): Promise<unknown> {
+    const em = this.getGlobalEntityManager(options.contextName);
+
+    return this.context.run([em], () => {
+      const forkedEm = this.getEntityManager(options.contextName);
+      forkedEm.resetTransactionContext();
+
+      return this.injector.alterAsync("$afterTransactionCommit", forkedEm);
+    });
+  }
+
+  private getEntityManager(contextName: string = DEFAULT_CONTEXT_NAME): EntityManager {
+    const em = this.context.get(contextName);
+
+    if (!em) {
+      throw new Error(`No such context: ${contextName}. Please check if the async context is lost in one of the asynchronous operations.`);
+    }
+
+    return em;
+  }
+}

package/src/interfaces/AfterTransactionCommit.ts

@@ -0,0 +1,5 @@
+import {EntityManager} from "@mikro-orm/core";
+
+export interface AfterTransactionCommit {
+  $afterTransactionCommit(em: EntityManager): Promise<unknown> | unknown;
+}

package/src/interfaces/BeforeTransactionCommit.ts

@@ -0,0 +1,5 @@
+import {EntityManager} from "@mikro-orm/core";
+
+export interface BeforeTransactionCommit {
+  $beforeTransactionCommit(em: EntityManager): Promise<unknown> | unknown;
+}

package/src/interfaces/RetryStrategy.ts

@@ -0,0 +1,5 @@
+export interface RetryStrategy {
+  acquire<T extends (...args: unknown[]) => unknown>(task: T): Promise<ReturnType<T> extends Promise<infer V> ? V : ReturnType<T>>;
+}
+
+export const RetryStrategy: unique symbol = Symbol("RetryStrategy");

package/src/services/MikroOrmContext.spec.ts

@@ -0,0 +1,95 @@
+import {EntityManager, RequestContext} from "@mikro-orm/core";
+import {deepEqual, instance as originalInstance, mock, reset, spy, verify, when} from "ts-mockito";
+
+import {MikroOrmContext} from "./MikroOrmContext.js";
+
+const instance = <T extends object>(m: T): T =>
+  new Proxy<T>(originalInstance(m), {
+    get(target, prop, receiver) {
+      if (["Symbol(Symbol.toPrimitive)", "Symbol(Symbol.isConcatSpreadable)", "length"].includes(prop.toString())) {
+        return undefined;
+      }
+      return Reflect.get(target, prop, receiver);
+    }
+  });
+
+describe("MikroOrmContext", () => {
+  const mockedEntityManager = mock<EntityManager>();
+
+  let spiedRequestContext: typeof RequestContext;
+  let entityManager!: EntityManager;
+  let context!: MikroOrmContext;
+
+  beforeEach(() => {
+    spiedRequestContext = spy(RequestContext);
+    entityManager = instance(mockedEntityManager);
+    context = new MikroOrmContext();
+  });
+  afterEach(() => reset<typeof RequestContext | EntityManager>(mockedEntityManager, spiedRequestContext));
+
+  describe("get", () => {
+    it("should return undefined if not such context", () => {
+      // act
+      const result = context.get("unknown");
+
+      // assert
+      expect(result).toBeUndefined();
+    });
+
+    it("should return entity manager if context is initialized", () => {
+      // arrange
+      when(spiedRequestContext.getEntityManager("context1")).thenReturn(entityManager);
+
+      // act
+      const result = context.get("context1");
+
+      // assert
+      expect(result).toBe(entityManager);
+    });
+  });
+
+  describe("wrap", () => {
+    it("should run a function within a mikro-orm context", async () => {
+      // arrange
+      const task = vi.fn();
+
+      // act
+      await context.run([entityManager], task);
+
+      // assert
+      verify(spiedRequestContext.create(deepEqual([entityManager]), task)).once();
+    });
+
+    it("should return a result of function execution", async () => {
+      // arrange
+      const task = vi.fn().mockResolvedValue("string");
+
+      // act
+      const result = await context.run([entityManager], task);
+
+      // assert
+      expect(result).toEqual("string");
+    });
+  });
+
+  describe("has", () => {
+    it("should return false if not such context", () => {
+      // act
+      const result = context.has("unknown");
+
+      // assert
+      expect(result).toBeFalsy();
+    });
+
+    it("should return true if context is initialized", () => {
+      // arrange
+      when(spiedRequestContext.getEntityManager("context1")).thenReturn(entityManager);
+
+      // act
+      const result = context.has("context1");
+
+      // assert
+      expect(result).toBe(true);
+    });
+  });
+});

package/src/services/MikroOrmContext.ts

@@ -0,0 +1,29 @@
+import {EntityManager, RequestContext} from "@mikro-orm/core";
+import {isFunction} from "@tsed/core";
+import {Injectable} from "@tsed/di";
+
+/**
+ * @internal Since 2022-06-20.
+ */
+@Injectable()
+export class MikroOrmContext {
+  public run(managers: EntityManager[], task: (...args: unknown[]) => unknown): Promise<unknown> {
+    // @ts-expect-error `RequestContext.createAsync` has been removed in favour of `RequestContext.create` since mikro-orm v6.0.0
+    if (isFunction(RequestContext.createAsync)) {
+      // @ts-expect-error see above
+      return RequestContext.createAsync(managers, task);
+    } else {
+      return RequestContext.create(managers, task) as Promise<unknown>;
+    }
+  }
+
+  public get(contextName?: string): EntityManager | undefined {
+    return RequestContext.getEntityManager(contextName);
+  }
+
+  public has(contextName?: string): boolean {
+    const manager = this.get(contextName);
+
+    return !!manager;
+  }
+}

package/src/services/MikroOrmFactory.ts

@@ -0,0 +1,16 @@
+import {MikroORM, Options} from "@mikro-orm/core";
+import {Inject, Injectable} from "@tsed/di";
+
+import {MikroOrmContext} from "./MikroOrmContext.js";
+
+@Injectable()
+export class MikroOrmFactory {
+  constructor(@Inject() private readonly context: MikroOrmContext) {}
+
+  public create(options: Options): Promise<MikroORM> {
+    return MikroORM.init({
+      ...options,
+      context: (name: string) => this.context.get(name)
+    });
+  }
+}