@rsdk/db.knex 2.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/.env +3 -0
  2. package/CHANGELOG.md +155 -0
  3. package/README.md +11 -0
  4. package/dist/index.d.ts +9 -0
  5. package/dist/index.js +15 -0
  6. package/dist/index.js.map +1 -0
  7. package/dist/inject-knex.decorator.d.ts +2 -0
  8. package/dist/inject-knex.decorator.js +8 -0
  9. package/dist/inject-knex.decorator.js.map +1 -0
  10. package/dist/internal/context.d.ts +77 -0
  11. package/dist/internal/context.js +220 -0
  12. package/dist/internal/context.js.map +1 -0
  13. package/dist/internal/exceptions.d.ts +65 -0
  14. package/dist/internal/exceptions.js +94 -0
  15. package/dist/internal/exceptions.js.map +1 -0
  16. package/dist/internal/initializer.d.ts +9 -0
  17. package/dist/internal/initializer.js +42 -0
  18. package/dist/internal/initializer.js.map +1 -0
  19. package/dist/internal/strategy.d.ts +18 -0
  20. package/dist/internal/strategy.js +75 -0
  21. package/dist/internal/strategy.js.map +1 -0
  22. package/dist/internal/test/strategy.test.e2e.d.ts +1 -0
  23. package/dist/internal/test/strategy.test.e2e.js +762 -0
  24. package/dist/internal/test/strategy.test.e2e.js.map +1 -0
  25. package/dist/internal/test/utils.d.ts +17 -0
  26. package/dist/internal/test/utils.js +21 -0
  27. package/dist/internal/test/utils.js.map +1 -0
  28. package/dist/knex.module.d.ts +5 -0
  29. package/dist/knex.module.js +34 -0
  30. package/dist/knex.module.js.map +1 -0
  31. package/dist/knex.plugin.d.ts +10 -0
  32. package/dist/knex.plugin.js +20 -0
  33. package/dist/knex.plugin.js.map +1 -0
  34. package/dist/providers/index.d.ts +4 -0
  35. package/dist/providers/index.js +21 -0
  36. package/dist/providers/index.js.map +1 -0
  37. package/dist/providers/knex-logger.adapter.d.ts +10 -0
  38. package/dist/providers/knex-logger.adapter.js +45 -0
  39. package/dist/providers/knex-logger.adapter.js.map +1 -0
  40. package/dist/providers/knex.config.d.ts +10 -0
  41. package/dist/providers/knex.config.js +76 -0
  42. package/dist/providers/knex.config.js.map +1 -0
  43. package/dist/providers/knex.factory.d.ts +13 -0
  44. package/dist/providers/knex.factory.js +96 -0
  45. package/dist/providers/knex.factory.js.map +1 -0
  46. package/dist/providers/knex.indicator.d.ts +8 -0
  47. package/dist/providers/knex.indicator.js +41 -0
  48. package/dist/providers/knex.indicator.js.map +1 -0
  49. package/dist/types.d.ts +12 -0
  50. package/dist/types.js +20 -0
  51. package/dist/types.js.map +1 -0
  52. package/jest.config.js +8 -0
  53. package/package.json +26 -0
  54. package/src/index.ts +10 -0
  55. package/src/inject-knex.decorator.ts +6 -0
  56. package/src/internal/context.ts +284 -0
  57. package/src/internal/exceptions.ts +91 -0
  58. package/src/internal/initializer.ts +43 -0
  59. package/src/internal/strategy.ts +116 -0
  60. package/src/internal/test/strategy.test.e2e.ts +1026 -0
  61. package/src/internal/test/utils.ts +26 -0
  62. package/src/knex.module.ts +28 -0
  63. package/src/knex.plugin.ts +21 -0
  64. package/src/providers/index.ts +4 -0
  65. package/src/providers/knex-logger.adapter.ts +32 -0
  66. package/src/providers/knex.config.ts +57 -0
  67. package/src/providers/knex.factory.ts +83 -0
  68. package/src/providers/knex.indicator.ts +22 -0
  69. package/src/types.ts +21 -0
  70. package/tsconfig.json +11 -0
@@ -0,0 +1,6 @@
1
+ import { Inject } from '@nestjs/common';
2
+
3
+ export const KNEX_INJECTION_TOKEN = Symbol('Knex');
4
+
5
+ export const InjectKnex = (): ParameterDecorator =>
6
+ Inject(KNEX_INJECTION_TOKEN);
@@ -0,0 +1,284 @@
1
+ /* eslint-disable @typescript-eslint/ban-ts-comment */
2
+ import { BaseContext } from '@rsdk/db';
3
+ import type { Knex } from 'knex';
4
+ /**
5
+ ts-ignore потому что в тайпингах этого нет, а тайпингов нет потому что knex ~~говно~~ написан на js, и тайпинги написаны руками,
6
+ руками которые не написали тайпинги для внутренних вещей
7
+ */
8
+ // @ts-ignore
9
+ import { default as Runner } from 'knex/lib/execution/runner';
10
+ // @ts-ignore
11
+ import makeKnex from 'knex/lib/knex-builder/make-knex';
12
+
13
+ import type { IsolationLevel } from '../types';
14
+ import { DEFAULT_ISOLATION_LEVEL, isolationLevels } from '../types';
15
+
16
+ import {
17
+ LayerMustBeInitialized,
18
+ LayersCountMoreThanNestDepth,
19
+ MustReleased,
20
+ NestUnavailableOnSuspendedContext,
21
+ StartWithFinalizedContextUnavailable,
22
+ UnexpectedRelease,
23
+ } from './exceptions';
24
+
25
+ export type KnexRunner = {
26
+ connection: any;
27
+ builder: Knex;
28
+ client: Knex;
29
+ run(...args: any[]): Promise<any>;
30
+ };
31
+
32
+ type KnexContextLayer = {
33
+ /**
34
+ * Проинициализированный trx
35
+ */
36
+ trx: Knex.Transaction;
37
+
38
+ /**
39
+ * Нужен прежде всего для поля `connection` которое инициализируется при первом вызове `run`
40
+ */
41
+ runner: KnexRunner;
42
+ };
43
+
44
+ export class KnexContext extends BaseContext<IsolationLevel> {
45
+ readonly isolationLevels = isolationLevels;
46
+
47
+ /**
48
+ * Завершена ли работа с этим контекстом
49
+ * Необходимо для контроля за тем чтобы не было переиспользований этого контекста
50
+ * @private
51
+ */
52
+ private _isReleased = false;
53
+
54
+ /**
55
+ * Массив слоёв в котором каждый trx и runner соответствует вложенности
56
+ * Необходимо для поддержки savepoint
57
+ * @private
58
+ */
59
+ private layers: KnexContextLayer[] = [];
60
+
61
+ /**
62
+ * Глубина вложенности
63
+ * Не путать с индексом вложенности
64
+ * По сути является необходимым количеством проинициализированных слоев
65
+ * @private
66
+ */
67
+ private nestDepth = 1;
68
+
69
+ private constructor(isolationLevel?: IsolationLevel);
70
+ private constructor(suspended: true);
71
+ private constructor(arg?: true | IsolationLevel) {
72
+ super(arg ?? DEFAULT_ISOLATION_LEVEL);
73
+ }
74
+
75
+ get isReleased(): boolean {
76
+ return this._isReleased;
77
+ }
78
+
79
+ /**
80
+ * Служебная функция для проверки проинициализирована ли транзакция.
81
+ * Не касается статуса инициализации текущего уровня вложенности
82
+ * @private
83
+ */
84
+ get transactionInitialized(): boolean {
85
+ return Boolean(this.layers.at(0)?.trx?.isTransaction);
86
+ }
87
+
88
+ static create(isolationLevel: IsolationLevel): KnexContext {
89
+ return new KnexContext(isolationLevel);
90
+ }
91
+
92
+ /**
93
+ * Создаёт инстанс контекста, который обеспечит изоляцию от внешнего контекста
94
+ * Прежде всего необходимо для имплементации NOT_SUPPORTED propagation
95
+ */
96
+ static createSuspended(): KnexContext {
97
+ return new KnexContext(true);
98
+ }
99
+
100
+ /**
101
+ * Создаём новый runner для запуска метода `run`
102
+ * Необходимо из-за того что builder определяется при создании `runner`
103
+ * @param knexRunner
104
+ */
105
+ createContextRunner(knexRunner: KnexRunner): KnexRunner | undefined {
106
+ const layer = this.layers.at(this.nestDepth - 1);
107
+ if (!layer) {
108
+ throw new LayerMustBeInitialized();
109
+ }
110
+
111
+ const transactionRunner = new Runner(layer.trx.client, knexRunner.builder);
112
+
113
+ /**
114
+ * Для того чтобы он точно использовал подключение уже существующего queryRunner, а не пытался его проинициализировать
115
+ * https://github.com/knex/knex/blob/42b91980b7de281a4c53910f9af32da4462a9c5a/lib/execution/runner.js#L30
116
+ * https://github.com/knex/knex/blob/42b91980b7de281a4c53910f9af32da4462a9c5a/lib/execution/runner.js#L281
117
+ *
118
+ * Такой же хак используется в самом knex
119
+ * https://github.com/knex/knex/blob/42b91980b7de281a4c53910f9af32da4462a9c5a/lib/execution/runner.js#L246
120
+ *
121
+ * Не думаю что есть повод беспокоиться о том что runner может взять подключение у builder, это делается форсировано самим пользователем,
122
+ * по крайней мере на данный момент я не нашёл использования этого внутри `knex`
123
+ */
124
+ transactionRunner.connection = layer.runner.connection;
125
+
126
+ return transactionRunner;
127
+ }
128
+
129
+ /**
130
+ * Метод инициализирует необходимые слои для корректной работы savepoint
131
+ * @param settledRunner
132
+ */
133
+ async initialize(settledRunner: KnexRunner): Promise<void> {
134
+ if (this.suspended) {
135
+ if (this.layers.length === 1) {
136
+ return;
137
+ }
138
+
139
+ const trx = makeKnex(settledRunner.client) as Knex;
140
+ const runner = new Runner(
141
+ trx.client,
142
+ /**
143
+ * Билдер в данном случае не имеет принципиального значения, сделано больше для соблюдения API, практического значения не имеет
144
+ */
145
+ settledRunner.builder,
146
+ );
147
+
148
+ this.layers = [
149
+ {
150
+ trx: trx as Knex.Transaction,
151
+ runner: runner,
152
+ },
153
+ ];
154
+ }
155
+
156
+ /**
157
+ * Получаем необходимое для инициализации количество слоёв,
158
+ * То есть количество вложенностей которое нам необходимо проинициализировать
159
+ */
160
+ const requiredLayerCount = this.nestDepth - this.layers.length;
161
+
162
+ for (let i = 0; i < requiredLayerCount; i++) {
163
+ const trx =
164
+ /**
165
+ * Если до этого транзакция уже была проинициализирована, то используем существующей trx для создания `savepoint`
166
+ */
167
+ this.layers.at(-1)?.trx ??
168
+ /**
169
+ * Создаём новый инстанс knex для начала нашей транзакции
170
+ * Элегантного способа использовать существующий нет ни возможности, ни практического смысла
171
+ */
172
+ (makeKnex(settledRunner.client) as Knex);
173
+
174
+ /**
175
+ * Если транзакции ещё не было, создаст её,
176
+ * иначе создаст `savepoint`
177
+ */
178
+ const initializedTrx = await trx.transaction();
179
+
180
+ const transactionRunner = new Runner(
181
+ initializedTrx.client,
182
+ /**
183
+ * Билдер в данном случае не имеет принципиального значения, сделано больше для соблюдения API, практического значения не имеет
184
+ */
185
+ settledRunner.builder,
186
+ );
187
+ const newKnexContextLayer = {
188
+ runner: transactionRunner,
189
+ trx: initializedTrx,
190
+ };
191
+
192
+ this.layers.push(newKnexContextLayer);
193
+ }
194
+ }
195
+
196
+ /**
197
+ * Должен быть вызван перед тем как запускать функцию, подразумевающую вложенный уровень транзакционности
198
+ */
199
+ addNestLayer(): void {
200
+ if (this.suspended) {
201
+ throw new NestUnavailableOnSuspendedContext();
202
+ }
203
+
204
+ this.nestDepth += 1;
205
+ }
206
+
207
+ async rollbackTransaction(): Promise<void> {
208
+ if (this.suspended) {
209
+ return;
210
+ }
211
+
212
+ /**
213
+ * Слой может быть не проинициализирован из-за того что внутри функции не было запросов к бд
214
+ */
215
+ await this.layers.at(this.nestDepth - 1)?.trx?.rollback();
216
+ }
217
+
218
+ async commitTransaction(): Promise<void> {
219
+ if (this.suspended) {
220
+ return;
221
+ }
222
+
223
+ /**
224
+ * Слой может быть не проинициализирован из-за того что внутри функции не было запросов к бд
225
+ */
226
+ await this.layers.at(this.nestDepth - 1)?.trx?.commit();
227
+ }
228
+
229
+ /**
230
+ * Завершает обработку вложенности
231
+ * @param mustRelease должны ли быть все транзакции завершены, а соединение возвращено в пул
232
+ */
233
+ finalize(mustRelease: boolean): void {
234
+ if (this.nestDepth < this.layers.length) {
235
+ /**
236
+ * Не должно быть ситуаций при которых мы попадаем сюда с количеством слоев больше чем уровень вложенности
237
+ */
238
+ throw new LayersCountMoreThanNestDepth();
239
+ }
240
+
241
+ this.nestDepth -= 1;
242
+
243
+ /**
244
+ * Удаляем обработанные слои
245
+ */
246
+ this.layers.splice(this.nestDepth);
247
+
248
+ /**
249
+ * Релизнули(закрыли) ли мы соединение
250
+ */
251
+ const isReleased = this.layers.length === 0;
252
+
253
+ this._isReleased = isReleased;
254
+
255
+ /**
256
+ * В обоих случаях в идеале завершать работу приложения так как часть операция может быть не выполнена, хотя должна была и наоборот
257
+ * И в качестве бонуса получим висящее соединение к СУБД которое нельзя использовать
258
+ */
259
+ if (mustRelease && !isReleased) {
260
+ throw new MustReleased();
261
+ }
262
+
263
+ if (isReleased && !mustRelease) {
264
+ throw new UnexpectedRelease();
265
+ }
266
+ }
267
+
268
+ /**
269
+ * Проинициализированы ли все необходимые слои транзакций
270
+ * Необходимо для тестов и внутренних процессов
271
+ */
272
+ isInitialized(): boolean {
273
+ return this.layers.length === this.nestDepth;
274
+ }
275
+
276
+ /**
277
+ * Можно ли начать использовать этот контекст
278
+ */
279
+ assertStart(): void {
280
+ if (this.nestDepth < 1) {
281
+ throw new StartWithFinalizedContextUnavailable();
282
+ }
283
+ }
284
+ }
@@ -0,0 +1,91 @@
1
+ import { InternalException } from '@rsdk/core';
2
+
3
+ /**
4
+ * Попытка начать выполнения функции в контексте при неподходящем состоянии контекста
5
+ */
6
+ export class StartWithFinalizedContextUnavailable extends InternalException {
7
+ constructor() {
8
+ super('Start with finalized context unavailable');
9
+ }
10
+ }
11
+
12
+ /**
13
+ * Попытка использовать queryRunner в момент когда слой для уровня вложенности ещё не проинициализирован
14
+ */
15
+ export class LayerMustBeInitialized extends InternalException {
16
+ constructor() {
17
+ super('Layer must be initialized');
18
+ }
19
+ }
20
+
21
+ export class FinalizeException extends InternalException {}
22
+
23
+ /**
24
+ * Ожидалось завершение работы с транзакцией, но не удовлетворены условия завершения (например транзакция не может быть закрыта из-за наличия незакрытых `savepoint`)
25
+ */
26
+ export class MustReleased extends InternalException {
27
+ constructor() {
28
+ super('Must released but conditions not satisfied');
29
+ }
30
+ }
31
+
32
+ /**
33
+ * Проинициализировано больше слоев чем текущий уровень вложенности
34
+ */
35
+ export class LayersCountMoreThanNestDepth extends FinalizeException {
36
+ constructor() {
37
+ super('Layers count more than nest depth');
38
+ }
39
+ }
40
+
41
+ export class ContextMustBeProvided extends InternalException {
42
+ constructor() {
43
+ super('Context must be provided');
44
+ }
45
+ }
46
+
47
+ /**
48
+ * Неожиданный релиз (закрытие/возвращение в пул) соединения
49
+ */
50
+ export class UnexpectedRelease extends InternalException {
51
+ constructor() {
52
+ super('Unexpected release connection');
53
+ }
54
+ }
55
+
56
+ /**
57
+ * Попытка использовать контекст когда работа с ним была завершена
58
+ * Например если не дождались завершения промиса использующего соединение
59
+ * @example
60
+ * runInContext(()=> {
61
+ * Promise.resolve().then(() => manager.query('SELECT 1'))
62
+ * })
63
+ *
64
+ * @example
65
+ * class UserController {
66
+ * constructor(
67
+ * private registerAttemptService: { registerAttemptToDb(): Promise<void> },
68
+ * private userService: { fetchUser(userId: UserId): Promise<User | null> }
69
+ * ) {}
70
+ *
71
+ * // @Get('/user')
72
+ * // @Transactional()
73
+ * async sum(@Query() query: { userId: UserId }): Promise<void> {
74
+ * this.registerAttemptService.registerAttemptToDb();
75
+ * return this.userService.fetchUser(query.userId);
76
+ * }
77
+ * }
78
+ */
79
+ export class ContextIsReleased extends InternalException {
80
+ constructor() {
81
+ super(
82
+ "Trying to use a context when it's already released (the function started in the context has been ended)",
83
+ );
84
+ }
85
+ }
86
+
87
+ export class NestUnavailableOnSuspendedContext extends InternalException {
88
+ constructor() {
89
+ super('Work with nesting context unavailable on suspended context');
90
+ }
91
+ }
@@ -0,0 +1,43 @@
1
+ /* eslint-disable @typescript-eslint/ban-ts-comment */
2
+ import { ContextStorage } from '@rsdk/db';
3
+ // @ts-ignore
4
+ import { default as Runner } from 'knex/lib/execution/runner';
5
+
6
+ import type { KnexContext, KnexRunner } from './context';
7
+ import { ContextIsReleased } from './exceptions';
8
+
9
+ const originalRun = Runner.prototype.run;
10
+
11
+ export class Initializer {
12
+ static readonly storage = new ContextStorage<KnexContext>();
13
+
14
+ /**
15
+ * Патчинг библиотеки для интеграции с асинхронным контекстом
16
+ */
17
+ static initialize(): void {
18
+ Object.defineProperty(Runner.prototype, 'run', {
19
+ value: async function (this: KnexRunner, ...args: any[]): Promise<any> {
20
+ const context = Initializer.storage.getContext();
21
+ if (!context) {
22
+ return originalRun.call(this, ...args);
23
+ }
24
+
25
+ if (context.isReleased) {
26
+ throw new ContextIsReleased();
27
+ }
28
+
29
+ /**
30
+ * Инициализируем контекст
31
+ */
32
+ await context.initialize(this);
33
+
34
+ /**
35
+ * Создаём ранер для выполнения запроса
36
+ */
37
+ const contextRunner = context.createContextRunner(this);
38
+
39
+ return originalRun.call(contextRunner, ...args);
40
+ },
41
+ });
42
+ }
43
+ }
@@ -0,0 +1,116 @@
1
+ import type { CallBack, TransactionalStrategy } from '@rsdk/db';
2
+
3
+ import type { IsolationLevel } from '../types';
4
+ import { DEFAULT_ISOLATION_LEVEL } from '../types';
5
+
6
+ import { KnexContext } from './context';
7
+ import { ContextMustBeProvided } from './exceptions';
8
+ import { Initializer } from './initializer';
9
+
10
+ export class KnexTransactionalStrategy
11
+ implements TransactionalStrategy<IsolationLevel, KnexContext>
12
+ {
13
+ getContext(): KnexContext | undefined {
14
+ return Initializer.storage.getContext();
15
+ }
16
+
17
+ runOutTransactionalContext<TArgs extends any[], TResult>(
18
+ fn: (...args: TArgs) => TResult,
19
+ ...args: TArgs
20
+ ): Promise<TResult> {
21
+ const context = KnexContext.createSuspended();
22
+ const wrapped = this.wrapInTransactionContext(true, fn);
23
+
24
+ return Initializer.storage.run(context, wrapped, ...args);
25
+ }
26
+
27
+ bindContext<TResult, TArgs extends any[]>(
28
+ fn: CallBack<TArgs, TResult>,
29
+ options: IsolationLevel = DEFAULT_ISOLATION_LEVEL,
30
+ ): CallBack<TArgs, Promise<TResult>> {
31
+ return (...args) => this.runInContext(options, fn, ...args);
32
+ }
33
+
34
+ isRunning(): boolean {
35
+ return Boolean(Initializer.storage.getContext());
36
+ }
37
+
38
+ /**
39
+ * Оборачивает функцию для корректного завершения транзакции, если она была проинициализирована внутри функции
40
+ * @param mustRelease Параметр указывает должны ли мы проверить что соединение было освобождено
41
+ * @param fn
42
+ */
43
+ wrapInTransactionContext<TResult, TArgs extends any[]>(
44
+ mustRelease: boolean,
45
+ fn: CallBack<TArgs, TResult>,
46
+ ): CallBack<TArgs, Promise<TResult>> {
47
+ return async (...args) => {
48
+ const context = Initializer.storage.getContext();
49
+
50
+ if (!context) {
51
+ /**
52
+ * Нельзя стартовать так как контекст отсутствует
53
+ */
54
+ throw new ContextMustBeProvided();
55
+ }
56
+
57
+ /**
58
+ * Можем ли мы стартовать с таким контекстом
59
+ */
60
+ context.assertStart();
61
+
62
+ try {
63
+ const result = await fn(...args);
64
+
65
+ await context.commitTransaction();
66
+
67
+ return result;
68
+ } catch (error) {
69
+ await context.rollbackTransaction();
70
+
71
+ throw error;
72
+ } finally {
73
+ context.finalize(mustRelease);
74
+ }
75
+ };
76
+ }
77
+
78
+ async runInContext<TResult, TArgs extends any[]>(
79
+ options: IsolationLevel,
80
+ fn: CallBack<TArgs, TResult>,
81
+ ...args: TArgs
82
+ ): Promise<TResult> {
83
+ const currentContext = Initializer.storage.getContext();
84
+ if (!currentContext) {
85
+ return await this.runFromNewContext(options, fn, ...args);
86
+ }
87
+
88
+ return await this.nestedExecute(currentContext, options, fn, ...args);
89
+ }
90
+
91
+ async runFromNewContext<TResult, TArgs extends any[]>(
92
+ isolationLevel: IsolationLevel,
93
+ fn: CallBack<TArgs, TResult>,
94
+ ...args: TArgs
95
+ ): Promise<TResult> {
96
+ const knexAsyncContextContext = KnexContext.create(isolationLevel);
97
+ const wrapped = this.wrapInTransactionContext(true, fn);
98
+
99
+ return Initializer.storage.run(knexAsyncContextContext, wrapped, ...args);
100
+ }
101
+
102
+ async nestedExecute<TResult, TArgs extends any[]>(
103
+ context: KnexContext,
104
+ isolationLevel: IsolationLevel,
105
+ fn: CallBack<TArgs, TResult>,
106
+ ...args: TArgs
107
+ ): Promise<TResult> {
108
+ context.assertIsolationCompatibility(isolationLevel);
109
+
110
+ const wrapped = this.wrapInTransactionContext(false, fn);
111
+
112
+ context.addNestLayer();
113
+
114
+ return wrapped(...args);
115
+ }
116
+ }