@venizia/ignis-kernel 0.4.8-8 → 0.4.8

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 (131) hide show
  1. package/dist/esm/base/applications/artifact-index.d.ts +3 -3
  2. package/dist/esm/base/applications/artifact-index.js.map +1 -1
  3. package/dist/esm/base/applications/body-limit.js +1 -1
  4. package/dist/esm/base/applications/body-limit.js.map +1 -1
  5. package/dist/esm/base/applications/common/types/application.d.ts +2 -2
  6. package/dist/esm/base/applications/common/types/application.js.map +1 -1
  7. package/dist/esm/base/applications/common/types/middlewares.d.ts +2 -2
  8. package/dist/esm/base/applications/common/types/middlewares.js.map +1 -1
  9. package/dist/esm/base/applications/rest.js +6 -1
  10. package/dist/esm/base/applications/rest.js.map +1 -1
  11. package/dist/esm/base/auth/authenticate/common/types/jwt.d.ts +1 -1
  12. package/dist/esm/base/auth/authenticate/common/types/jwt.js.map +1 -1
  13. package/dist/esm/base/auth/authenticate/common/types/strategy.d.ts +2 -3
  14. package/dist/esm/base/auth/authenticate/common/types/strategy.js.map +1 -1
  15. package/dist/esm/base/auth/authenticate/strategies/strategy-registry.d.ts +1 -1
  16. package/dist/esm/base/auth/authenticate/strategies/strategy-registry.js +1 -1
  17. package/dist/esm/base/auth/authenticate/strategies/strategy-registry.js.map +1 -1
  18. package/dist/esm/base/auth/authorize/providers/request-domain.js +2 -1
  19. package/dist/esm/base/auth/authorize/providers/request-domain.js.map +1 -1
  20. package/dist/esm/base/controllers/common/types/route.d.ts +13 -4
  21. package/dist/esm/base/controllers/common/types/route.js.map +1 -1
  22. package/dist/esm/base/controllers/factory/controller.d.ts +3 -4
  23. package/dist/esm/base/controllers/factory/controller.js +0 -1
  24. package/dist/esm/base/controllers/factory/controller.js.map +1 -1
  25. package/dist/esm/base/controllers/factory/crud/abstract.d.ts +3 -4
  26. package/dist/esm/base/controllers/factory/crud/abstract.js.map +1 -1
  27. package/dist/esm/base/controllers/factory/definition.d.ts +21 -1
  28. package/dist/esm/base/controllers/factory/definition.js +45 -31
  29. package/dist/esm/base/controllers/factory/definition.js.map +1 -1
  30. package/dist/esm/base/controllers/factory/index.d.ts +1 -0
  31. package/dist/esm/base/controllers/factory/index.js +1 -0
  32. package/dist/esm/base/controllers/factory/index.js.map +1 -1
  33. package/dist/esm/base/controllers/factory/injection.d.ts +38 -0
  34. package/dist/esm/base/controllers/factory/injection.js +54 -0
  35. package/dist/esm/base/controllers/factory/injection.js.map +1 -0
  36. package/dist/esm/base/controllers/rest/abstract.js +1 -1
  37. package/dist/esm/base/controllers/rest/abstract.js.map +1 -1
  38. package/dist/esm/base/controllers/rest/base.d.ts +3 -3
  39. package/dist/esm/base/controllers/rest/base.js.map +1 -1
  40. package/dist/esm/base/datasources/abstract.d.ts +4 -92
  41. package/dist/esm/base/datasources/abstract.js +3 -217
  42. package/dist/esm/base/datasources/abstract.js.map +1 -1
  43. package/dist/esm/base/datasources/common/types.d.ts +2 -2
  44. package/dist/esm/base/datasources/common/types.js.map +1 -1
  45. package/dist/esm/base/datasources/index.d.ts +1 -0
  46. package/dist/esm/base/datasources/index.js +1 -0
  47. package/dist/esm/base/datasources/index.js.map +1 -1
  48. package/dist/esm/base/datasources/root.d.ts +107 -0
  49. package/dist/esm/base/datasources/root.js +237 -0
  50. package/dist/esm/base/datasources/root.js.map +1 -0
  51. package/dist/esm/base/events/event-bus.js.map +1 -1
  52. package/dist/esm/base/metadata/index.d.ts +1 -1
  53. package/dist/esm/base/metadata/index.js +1 -1
  54. package/dist/esm/base/metadata/injectors.d.ts +1 -1
  55. package/dist/esm/base/metadata/persistents/datasource.d.ts +21 -0
  56. package/dist/esm/base/metadata/persistents/datasource.js +46 -0
  57. package/dist/esm/base/metadata/persistents/datasource.js.map +1 -0
  58. package/dist/esm/base/metadata/persistents/index.d.ts +5 -0
  59. package/dist/esm/base/metadata/persistents/index.js +5 -0
  60. package/dist/esm/base/metadata/persistents/index.js.map +1 -0
  61. package/dist/esm/base/metadata/persistents/model.d.ts +18 -0
  62. package/dist/esm/base/metadata/persistents/model.js +64 -0
  63. package/dist/esm/base/metadata/persistents/model.js.map +1 -0
  64. package/dist/esm/base/metadata/persistents/repository/index.d.ts +19 -0
  65. package/dist/esm/base/metadata/persistents/repository/index.js +32 -0
  66. package/dist/esm/base/metadata/persistents/repository/index.js.map +1 -0
  67. package/dist/esm/base/metadata/persistents/repository/injection.d.ts +15 -0
  68. package/dist/esm/base/metadata/persistents/repository/injection.js +64 -0
  69. package/dist/esm/base/metadata/persistents/repository/injection.js.map +1 -0
  70. package/dist/esm/base/metadata/persistents/repository/resolve.d.ts +15 -0
  71. package/dist/esm/base/metadata/persistents/repository/resolve.js +76 -0
  72. package/dist/esm/base/metadata/persistents/repository/resolve.js.map +1 -0
  73. package/dist/esm/base/metadata/persistents/repository/validate.d.ts +15 -0
  74. package/dist/esm/base/metadata/persistents/repository/validate.js +50 -0
  75. package/dist/esm/base/metadata/persistents/repository/validate.js.map +1 -0
  76. package/dist/esm/base/models/common/utilities.d.ts +1 -1
  77. package/dist/esm/base/repositories/common/response-reader.d.ts +30 -0
  78. package/dist/esm/base/repositories/common/response-reader.js +53 -0
  79. package/dist/esm/base/repositories/common/response-reader.js.map +1 -1
  80. package/dist/esm/base/repositories/common/types/contracts.d.ts +2 -2
  81. package/dist/esm/base/repositories/common/types/contracts.js.map +1 -1
  82. package/dist/esm/base/repositories/common/types/options.d.ts +2 -2
  83. package/dist/esm/base/repositories/common/types/options.js.map +1 -1
  84. package/dist/esm/base/repositories/common/types/query.d.ts +6 -15
  85. package/dist/esm/base/repositories/common/types/query.js.map +1 -1
  86. package/dist/esm/base/repositories/core/abstract.d.ts +6 -6
  87. package/dist/esm/base/repositories/core/abstract.js.map +1 -1
  88. package/dist/esm/base/repositories/query-schemas/index.js +7 -0
  89. package/dist/esm/base/repositories/query-schemas/index.js.map +1 -1
  90. package/dist/esm/helpers/inversion/common/types/model.d.ts +1 -1
  91. package/dist/esm/helpers/inversion/common/types/model.js.map +1 -1
  92. package/dist/esm/helpers/inversion/mixins/artifact.mixin.d.ts +4 -3
  93. package/dist/esm/helpers/inversion/mixins/artifact.mixin.js +1 -0
  94. package/dist/esm/helpers/inversion/mixins/artifact.mixin.js.map +1 -1
  95. package/dist/esm/helpers/inversion/mixins/controllers/controller.d.ts +4 -3
  96. package/dist/esm/helpers/inversion/mixins/controllers/controller.js +1 -0
  97. package/dist/esm/helpers/inversion/mixins/controllers/controller.js.map +1 -1
  98. package/dist/esm/helpers/inversion/mixins/controllers/grpc.d.ts +4 -3
  99. package/dist/esm/helpers/inversion/mixins/controllers/grpc.js +1 -0
  100. package/dist/esm/helpers/inversion/mixins/controllers/grpc.js.map +1 -1
  101. package/dist/esm/helpers/inversion/mixins/controllers/rest.d.ts +4 -3
  102. package/dist/esm/helpers/inversion/mixins/controllers/rest.js +1 -0
  103. package/dist/esm/helpers/inversion/mixins/controllers/rest.js.map +1 -1
  104. package/dist/esm/helpers/inversion/mixins/datasource.mixin.d.ts +4 -3
  105. package/dist/esm/helpers/inversion/mixins/datasource.mixin.js +1 -0
  106. package/dist/esm/helpers/inversion/mixins/datasource.mixin.js.map +1 -1
  107. package/dist/esm/helpers/inversion/mixins/model.mixin.d.ts +4 -3
  108. package/dist/esm/helpers/inversion/mixins/model.mixin.js +1 -0
  109. package/dist/esm/helpers/inversion/mixins/model.mixin.js.map +1 -1
  110. package/dist/esm/helpers/inversion/mixins/repository.mixin.d.ts +9 -8
  111. package/dist/esm/helpers/inversion/mixins/repository.mixin.js +6 -6
  112. package/dist/esm/helpers/inversion/mixins/repository.mixin.js.map +1 -1
  113. package/dist/esm/helpers/inversion/registry.d.ts +26 -26
  114. package/dist/esm/helpers/inversion/registry.js.map +1 -1
  115. package/dist/esm/helpers/singleton-realm.js +5 -4
  116. package/dist/esm/helpers/singleton-realm.js.map +1 -1
  117. package/dist/esm/metadata.d.ts +1 -1
  118. package/dist/esm/metadata.js +1 -1
  119. package/dist/esm/repository.d.ts +1 -0
  120. package/dist/esm/repository.js +1 -0
  121. package/dist/esm/repository.js.map +1 -1
  122. package/dist/esm/utilities/index.d.ts +1 -0
  123. package/dist/esm/utilities/index.js +1 -0
  124. package/dist/esm/utilities/index.js.map +1 -1
  125. package/dist/esm/utilities/toggle.utility.d.ts +22 -0
  126. package/dist/esm/utilities/toggle.utility.js +16 -0
  127. package/dist/esm/utilities/toggle.utility.js.map +1 -0
  128. package/package.json +5 -5
  129. package/dist/esm/base/metadata/persistents.d.ts +0 -54
  130. package/dist/esm/base/metadata/persistents.js +0 -302
  131. package/dist/esm/base/metadata/persistents.js.map +0 -1
@@ -1,100 +1,12 @@
1
- import type { AnyType, TClass, ValueOrPromise } from '@venizia/ignis-helpers/common';
2
- import { BaseHelper } from '@venizia/ignis-helpers/core';
3
- import type { IDataSource, IDataSourceCapabilities, IDataSourceOpening, ITransaction, ITransactionOptions, TAnyDataSourceSchema, TDataSourceOpenMode } from './common/index.js';
4
- import { OPENING_HANDLES } from './opening-handles.js';
5
- /**
6
- * Brands the datasource root so `@repository` can recognise a subclass WITHOUT `instanceof`.
7
- *
8
- * Two copies of this package give two `AbstractDataSource` classes, and `instanceof` across them is
9
- * false - the same trap `isApplicationError` exists to avoid for `ApplicationError`. `Symbol.for` is
10
- * realm-keyed, so both copies produce this exact symbol, and a static is inherited by every
11
- * subclass however deep.
12
- */
13
- export declare const DATA_SOURCE_BRAND: unique symbol;
14
- /** True for `AbstractDataSource` itself and for any class extending it, across package copies. */
15
- export declare const isDataSourceClass: (value: unknown) => value is TClass<AnyType>;
1
+ import type { TClass } from '@venizia/ignis-helpers/common';
2
+ import type { TAnyDataSourceSchema, TDataSourceOpenMode } from './common/index.js';
3
+ import { DataSourceRoot } from './root.js';
16
4
  /** Engine-neutral datasource root - NO SQL members. Every connector family extends this. */
17
- export declare abstract class AbstractDataSource<Settings extends object = {}, Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema, ConfigurableOptions extends object = {}> extends BaseHelper implements IDataSource<Settings, Schema, ConfigurableOptions> {
18
- /** Read by {@link isDataSourceClass}. Static, so every subclass inherits it. */
19
- static readonly [DATA_SOURCE_BRAND] = true;
20
- name: string;
21
- settings: Settings;
22
- schema: Schema;
23
- abstract configure(opts?: ConfigurableOptions, opening?: IDataSourceOpening): ValueOrPromise<void>;
24
- /** The options the boot would have given `configure()`, kept for the open that the first use starts. */
25
- private deferredOptions?;
26
- /** The open in flight: every call that arrives meanwhile awaits this one promise. */
27
- private opening?;
28
- /**
29
- * An open that outlived its timeout and has not settled. Nothing is retried until it has: two `configure()` must never
30
- * run at once, and when it does settle what it built is closed, never published.
31
- */
32
- private abandoned?;
33
- private isOpened;
34
- private isShutDown;
35
- /**
36
- * Whether this family can open on first use: only a family whose every entry point first awaits {@link ensureOpen}
37
- * says yes (the relational one does). A family that does not is refused at boot rather than left half-working.
38
- */
39
- protected supportsDeferredOpen(): boolean;
5
+ export declare abstract class AbstractDataSource<Settings extends object = {}, Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema, ConfigurableOptions extends object = {}> extends DataSourceRoot<Settings, Schema, ConfigurableOptions> {
40
6
  /** The `open.on` of `@datasource`, `start` when unset. */
41
7
  getOpenMode(): TDataSourceOpenMode;
42
- isOpenDeferred(): boolean;
43
8
  /** The `open.timeoutMs` of `@datasource` (ms; `0` waits for ever), 60 s when unset. */
44
9
  getOpenTimeoutMs(): number;
45
- /**
46
- * Whether the datasource is open. One that opens on first use: after the first use has finished, until `close()`. One that
47
- * opens at start: from the moment the application has started it, until `close()`.
48
- */
49
- isOpen(): boolean;
50
- /** Whether the first use is opening the datasource right now. */
51
- isOpening(): boolean;
52
- /** Whether `close()` has begun. A datasource that opens on first use is not reopened after it. */
53
- isClosed(): boolean;
54
- /**
55
- * What the application boot calls to get the handles it passes to `configure()` of a datasource that opens at start. Keyed by a
56
- * symbol the package does not export, so nothing else can obtain the handles: see {@link OPENING_HANDLES}.
57
- */
58
- [OPENING_HANDLES](): IDataSourceOpening;
59
- /**
60
- * The handles `configure()` gets as its second argument, in both modes. The root has no connector, client or transaction to
61
- * hand out; a family that has them overrides this. Protected: the only ways out are the argument of `configure()` and the
62
- * boot's private key.
63
- */
64
- protected createOpening(): IDataSourceOpening;
65
- /**
66
- * The boot's replacement for `configure()` on a datasource that opens on first use: records the options and opens nothing.
67
- * Refused for a family that cannot honour it.
68
- */
69
- deferOpen(opts: {
70
- options?: ConfigurableOptions;
71
- }): void;
72
- /**
73
- * Resolves once the datasource is open. At once for one that opens with the application. Otherwise the first caller
74
- * starts `configure()` and the rest await the same promise, so it runs once; a failure rejects all of them, undoes what the
75
- * failed `configure()` left ({@link discardPartialOpen}) and clears the slot, so the next call opens afresh. After
76
- * `close()` it rejects: a stopped application does not reopen its datasources.
77
- */
78
- ensureOpen(): Promise<void>;
79
- private runOpen;
80
- /** When an abandoned open finally settles, whatever it built is closed (it was never published) and retries are allowed again. */
81
- private settleAbandoned;
82
- private discardOpenAttempt;
83
- /** Undoes what a `configure()` that threw left behind, so the next open starts clean. The root holds nothing; a family that keeps a client overrides it. */
84
- protected discardPartialOpen(): ValueOrPromise<void>;
85
- /**
86
- * Waits for an open in flight and refuses any later one. A family's `close()` calls it first, so a stop that arrives
87
- * during the first use closes what that open built instead of racing it.
88
- */
89
- protected settleOpening(): Promise<void>;
90
- getSettings(): Settings;
91
- getSchema(): Schema;
92
- /** Capability probe, overridden by connectors that support it (e.g. postgres reports `{ transactions: true }`). */
93
- getCapabilities(): IDataSourceCapabilities;
94
- /** Nothing to release at this root; a family that holds a connection overrides it. */
95
- close(): Promise<void>;
96
- /** Defaults to throwing NotSupported - only connectors with real transaction support override this; async so callers get a rejected promise, not a synchronous throw that skips try/catch. */
97
- beginTransaction(_opts?: ITransactionOptions): Promise<ITransaction>;
98
10
  /** Model classes bound to this datasource via `@repository` metadata - paradigm-free (no schema/relation resolution). */
99
11
  protected getBoundModelClasses(): Array<TClass<unknown>>;
100
12
  /** Walks model classes bound to this datasource, reads a connector-specific artifact via `read`, and returns a name-keyed registry - skips undefined reads, throws on duplicate names, honors `autoDiscovery: false`. */
@@ -1,41 +1,9 @@
1
- var _a;
2
1
  import { MetadataRegistry } from '../../helpers/inversion/index.js';
3
- import { NotSupportedUtility } from '../../utilities/index.js';
4
- import { BaseHelper, getError } from '@venizia/ignis-helpers/core';
2
+ import { getError } from '@venizia/ignis-helpers/core';
5
3
  import { DataSourceOpenDefaults, DataSourceOpenModes } from './common/index.js';
6
- import { OPENING_HANDLES } from './opening-handles.js';
7
- /**
8
- * Brands the datasource root so `@repository` can recognise a subclass WITHOUT `instanceof`.
9
- *
10
- * Two copies of this package give two `AbstractDataSource` classes, and `instanceof` across them is
11
- * false - the same trap `isApplicationError` exists to avoid for `ApplicationError`. `Symbol.for` is
12
- * realm-keyed, so both copies produce this exact symbol, and a static is inherited by every
13
- * subclass however deep.
14
- */
15
- export const DATA_SOURCE_BRAND = Symbol.for('@venizia/ignis-kernel:abstract-data-source');
16
- /** True for `AbstractDataSource` itself and for any class extending it, across package copies. */
17
- export const isDataSourceClass = (value) => {
18
- return typeof value === 'function' && DATA_SOURCE_BRAND in value;
19
- };
20
- /** The two ways a race between the open and its timeout can end. */
21
- const OPEN_DONE = 'done';
22
- const OPEN_TIMED_OUT = 'timed-out';
4
+ import { DataSourceRoot } from './root.js';
23
5
  /** Engine-neutral datasource root - NO SQL members. Every connector family extends this. */
24
- export class AbstractDataSource extends BaseHelper {
25
- constructor() {
26
- super(...arguments);
27
- this.isOpened = false;
28
- this.isShutDown = false;
29
- }
30
- /** Read by {@link isDataSourceClass}. Static, so every subclass inherits it. */
31
- static { this[_a] = true; }
32
- /**
33
- * Whether this family can open on first use: only a family whose every entry point first awaits {@link ensureOpen}
34
- * says yes (the relational one does). A family that does not is refused at boot rather than left half-working.
35
- */
36
- supportsDeferredOpen() {
37
- return false;
38
- }
6
+ export class AbstractDataSource extends DataSourceRoot {
39
7
  /** The `open.on` of `@datasource`, `start` when unset. */
40
8
  getOpenMode() {
41
9
  const metadata = MetadataRegistry.getInstance().getDataSourceMetadata({
@@ -43,9 +11,6 @@ export class AbstractDataSource extends BaseHelper {
43
11
  });
44
12
  return metadata?.open?.on ?? DataSourceOpenModes.START;
45
13
  }
46
- isOpenDeferred() {
47
- return this.getOpenMode() === DataSourceOpenModes.FIRST_USE;
48
- }
49
14
  /** The `open.timeoutMs` of `@datasource` (ms; `0` waits for ever), 60 s when unset. */
50
15
  getOpenTimeoutMs() {
51
16
  const metadata = MetadataRegistry.getInstance().getDataSourceMetadata({
@@ -53,185 +18,6 @@ export class AbstractDataSource extends BaseHelper {
53
18
  });
54
19
  return metadata?.open?.timeoutMs ?? DataSourceOpenDefaults.TIMEOUT_MS;
55
20
  }
56
- /**
57
- * Whether the datasource is open. One that opens on first use: after the first use has finished, until `close()`. One that
58
- * opens at start: from the moment the application has started it, until `close()`.
59
- */
60
- isOpen() {
61
- if (this.isShutDown) {
62
- return false;
63
- }
64
- return this.isOpenDeferred() ? this.isOpened : true;
65
- }
66
- /** Whether the first use is opening the datasource right now. */
67
- isOpening() {
68
- return this.opening !== undefined;
69
- }
70
- /** Whether `close()` has begun. A datasource that opens on first use is not reopened after it. */
71
- isClosed() {
72
- return this.isShutDown;
73
- }
74
- /**
75
- * What the application boot calls to get the handles it passes to `configure()` of a datasource that opens at start. Keyed by a
76
- * symbol the package does not export, so nothing else can obtain the handles: see {@link OPENING_HANDLES}.
77
- */
78
- [(_a = DATA_SOURCE_BRAND, OPENING_HANDLES)]() {
79
- return this.createOpening();
80
- }
81
- /**
82
- * The handles `configure()` gets as its second argument, in both modes. The root has no connector, client or transaction to
83
- * hand out; a family that has them overrides this. Protected: the only ways out are the argument of `configure()` and the
84
- * boot's private key.
85
- */
86
- createOpening() {
87
- const refuse = (member) => NotSupportedUtility.throwNotSupported({
88
- scope: this.constructor.name,
89
- feature: `opening.${member}`,
90
- logger: this.logger,
91
- });
92
- return {
93
- getConnector: () => refuse('getConnector'),
94
- getClient: () => refuse('getClient'),
95
- beginTransaction: () => Promise.resolve().then(() => refuse('beginTransaction')),
96
- };
97
- }
98
- /**
99
- * The boot's replacement for `configure()` on a datasource that opens on first use: records the options and opens nothing.
100
- * Refused for a family that cannot honour it.
101
- */
102
- deferOpen(opts) {
103
- if (!this.supportsDeferredOpen()) {
104
- throw getError({
105
- message: `[${this.constructor.name}][deferOpen] open: 'first-use' is not supported by this datasource family | Use open: { on: 'start' }, or remove the option`,
106
- });
107
- }
108
- this.deferredOptions = opts.options;
109
- }
110
- /**
111
- * Resolves once the datasource is open. At once for one that opens with the application. Otherwise the first caller
112
- * starts `configure()` and the rest await the same promise, so it runs once; a failure rejects all of them, undoes what the
113
- * failed `configure()` left ({@link discardPartialOpen}) and clears the slot, so the next call opens afresh. After
114
- * `close()` it rejects: a stopped application does not reopen its datasources.
115
- */
116
- ensureOpen() {
117
- if (!this.isOpenDeferred()) {
118
- return Promise.resolve();
119
- }
120
- // Closed first: a call after `close()` is told so, whether or not the datasource had been opened.
121
- if (this.isShutDown) {
122
- return Promise.reject(getError({
123
- message: `[${this.constructor.name}][ensureOpen] The datasource is closed | It opens on first use only before close()`,
124
- }));
125
- }
126
- if (this.isOpened) {
127
- return Promise.resolve();
128
- }
129
- if (this.abandoned) {
130
- return Promise.reject(getError({
131
- message: `[${this.constructor.name}][ensureOpen] The previous open is still running after its timeout | It is retried once it has settled`,
132
- }));
133
- }
134
- this.opening ??= this.runOpen();
135
- return this.opening;
136
- }
137
- async runOpen() {
138
- const timeoutMs = this.getOpenTimeoutMs();
139
- const work = Promise.resolve().then(() => this.configure(this.deferredOptions, this.createOpening()));
140
- let timer;
141
- const expired = new Promise((resolve) => {
142
- if (timeoutMs > 0) {
143
- timer = setTimeout(() => resolve(OPEN_TIMED_OUT), timeoutMs);
144
- }
145
- });
146
- try {
147
- const outcome = await Promise.race([work.then(() => OPEN_DONE), expired]);
148
- if (outcome === OPEN_TIMED_OUT) {
149
- this.abandoned = this.settleAbandoned({ work });
150
- throw getError({
151
- message: `[${this.constructor.name}][ensureOpen] The open did not finish within ${timeoutMs} ms | Does configure() await the datasource (a repository, ensureOpen)? Use the opening argument inside configure()`,
152
- });
153
- }
154
- this.isOpened = true;
155
- }
156
- catch (error) {
157
- await this.discardOpenAttempt();
158
- throw error;
159
- }
160
- finally {
161
- if (timer !== undefined) {
162
- clearTimeout(timer);
163
- }
164
- this.opening = undefined;
165
- }
166
- }
167
- /** When an abandoned open finally settles, whatever it built is closed (it was never published) and retries are allowed again. */
168
- async settleAbandoned(opts) {
169
- try {
170
- await opts.work;
171
- // eslint-disable-next-line venizia/no-silent-catch -- the abandoned attempt's own outcome was already reported by the timeout; only its clean-up matters now
172
- }
173
- catch {
174
- // Falls through to the clean-up.
175
- }
176
- await this.discardOpenAttempt();
177
- this.abandoned = undefined;
178
- }
179
- async discardOpenAttempt() {
180
- try {
181
- await this.discardPartialOpen();
182
- // eslint-disable-next-line venizia/no-silent-catch -- the open's own error is what the caller must see: a failed clean-up is logged, never thrown over it
183
- }
184
- catch (cleanupError) {
185
- this.logger
186
- .for(this.ensureOpen.name)
187
- .warn('Clean-up after a failed open also failed | error: %s', cleanupError);
188
- }
189
- }
190
- /** Undoes what a `configure()` that threw left behind, so the next open starts clean. The root holds nothing; a family that keeps a client overrides it. */
191
- discardPartialOpen() { }
192
- /**
193
- * Waits for an open in flight and refuses any later one. A family's `close()` calls it first, so a stop that arrives
194
- * during the first use closes what that open built instead of racing it.
195
- */
196
- async settleOpening() {
197
- this.isShutDown = true;
198
- try {
199
- await this.opening;
200
- // eslint-disable-next-line venizia/no-silent-catch -- the failed open was reported to its own waiters; stopping goes on
201
- }
202
- catch (openError) {
203
- this.logger
204
- .for(this.close.name)
205
- .debug('The open in flight failed while stopping | error: %s', openError);
206
- }
207
- }
208
- getSettings() {
209
- return this.settings;
210
- }
211
- getSchema() {
212
- if (!this.schema) {
213
- throw getError({
214
- message: `[${this.constructor.name}] Schema not initialized. Override getSchema() or provide schema in constructor.`,
215
- });
216
- }
217
- return this.schema;
218
- }
219
- /** Capability probe, overridden by connectors that support it (e.g. postgres reports `{ transactions: true }`). */
220
- getCapabilities() {
221
- return { transactions: false };
222
- }
223
- /** Nothing to release at this root; a family that holds a connection overrides it. */
224
- close() {
225
- return Promise.resolve();
226
- }
227
- /** Defaults to throwing NotSupported - only connectors with real transaction support override this; async so callers get a rejected promise, not a synchronous throw that skips try/catch. */
228
- async beginTransaction(_opts) {
229
- return NotSupportedUtility.throwNotSupported({
230
- scope: this.constructor.name,
231
- feature: 'Transactions',
232
- logger: this.logger,
233
- });
234
- }
235
21
  /** Model classes bound to this datasource via `@repository` metadata - paradigm-free (no schema/relation resolution). */
236
22
  getBoundModelClasses() {
237
23
  return MetadataRegistry.getInstance().getModelClasses({
@@ -1 +1 @@
1
- {"version":3,"file":"abstract.js","sourceRoot":"","sources":["../../../../src/base/datasources/abstract.ts"],"names":[],"mappings":"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","sourcesContent":["import { MetadataRegistry } from '@/helpers/inversion';\nimport { NotSupportedUtility } from '@/utilities';\nimport type { AnyType, TClass, ValueOrPromise } from '@venizia/ignis-helpers/common';\nimport { BaseHelper, getError } from '@venizia/ignis-helpers/core';\nimport type {\n IDataSource,\n IDataSourceCapabilities,\n IDataSourceOpening,\n ITransaction,\n ITransactionOptions,\n TAnyDataSourceSchema,\n TDataSourceOpenMode,\n} from './common';\nimport { DataSourceOpenDefaults, DataSourceOpenModes } from './common';\nimport { OPENING_HANDLES } from './opening-handles';\n\n/**\n * Brands the datasource root so `@repository` can recognise a subclass WITHOUT `instanceof`.\n *\n * Two copies of this package give two `AbstractDataSource` classes, and `instanceof` across them is\n * false - the same trap `isApplicationError` exists to avoid for `ApplicationError`. `Symbol.for` is\n * realm-keyed, so both copies produce this exact symbol, and a static is inherited by every\n * subclass however deep.\n */\nexport const DATA_SOURCE_BRAND = Symbol.for('@venizia/ignis-kernel:abstract-data-source');\n\n/** True for `AbstractDataSource` itself and for any class extending it, across package copies. */\nexport const isDataSourceClass = (value: unknown): value is TClass<AnyType> => {\n return typeof value === 'function' && DATA_SOURCE_BRAND in value;\n};\n\n/** The two ways a race between the open and its timeout can end. */\nconst OPEN_DONE = 'done';\nconst OPEN_TIMED_OUT = 'timed-out';\n\n/** Engine-neutral datasource root - NO SQL members. Every connector family extends this. */\nexport abstract class AbstractDataSource<\n Settings extends object = {},\n Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,\n ConfigurableOptions extends object = {},\n>\n extends BaseHelper\n implements IDataSource<Settings, Schema, ConfigurableOptions>\n{\n /** Read by {@link isDataSourceClass}. Static, so every subclass inherits it. */\n static readonly [DATA_SOURCE_BRAND] = true;\n\n name: string;\n settings: Settings;\n schema: Schema;\n\n abstract configure(\n opts?: ConfigurableOptions,\n opening?: IDataSourceOpening,\n ): ValueOrPromise<void>;\n\n /** The options the boot would have given `configure()`, kept for the open that the first use starts. */\n private deferredOptions?: ConfigurableOptions;\n\n /** The open in flight: every call that arrives meanwhile awaits this one promise. */\n private opening?: Promise<void>;\n\n /**\n * An open that outlived its timeout and has not settled. Nothing is retried until it has: two `configure()` must never\n * run at once, and when it does settle what it built is closed, never published.\n */\n private abandoned?: Promise<void>;\n\n private isOpened = false;\n private isShutDown = false;\n\n /**\n * Whether this family can open on first use: only a family whose every entry point first awaits {@link ensureOpen}\n * says yes (the relational one does). A family that does not is refused at boot rather than left half-working.\n */\n protected supportsDeferredOpen(): boolean {\n return false;\n }\n\n /** The `open.on` of `@datasource`, `start` when unset. */\n getOpenMode(): TDataSourceOpenMode {\n const metadata = MetadataRegistry.getInstance().getDataSourceMetadata({\n target: this.constructor,\n });\n\n return metadata?.open?.on ?? DataSourceOpenModes.START;\n }\n\n isOpenDeferred(): boolean {\n return this.getOpenMode() === DataSourceOpenModes.FIRST_USE;\n }\n\n /** The `open.timeoutMs` of `@datasource` (ms; `0` waits for ever), 60 s when unset. */\n getOpenTimeoutMs(): number {\n const metadata = MetadataRegistry.getInstance().getDataSourceMetadata({\n target: this.constructor,\n });\n\n return metadata?.open?.timeoutMs ?? DataSourceOpenDefaults.TIMEOUT_MS;\n }\n\n /**\n * Whether the datasource is open. One that opens on first use: after the first use has finished, until `close()`. One that\n * opens at start: from the moment the application has started it, until `close()`.\n */\n isOpen(): boolean {\n if (this.isShutDown) {\n return false;\n }\n\n return this.isOpenDeferred() ? this.isOpened : true;\n }\n\n /** Whether the first use is opening the datasource right now. */\n isOpening(): boolean {\n return this.opening !== undefined;\n }\n\n /** Whether `close()` has begun. A datasource that opens on first use is not reopened after it. */\n isClosed(): boolean {\n return this.isShutDown;\n }\n\n /**\n * What the application boot calls to get the handles it passes to `configure()` of a datasource that opens at start. Keyed by a\n * symbol the package does not export, so nothing else can obtain the handles: see {@link OPENING_HANDLES}.\n */\n [OPENING_HANDLES](): IDataSourceOpening {\n return this.createOpening();\n }\n\n /**\n * The handles `configure()` gets as its second argument, in both modes. The root has no connector, client or transaction to\n * hand out; a family that has them overrides this. Protected: the only ways out are the argument of `configure()` and the\n * boot's private key.\n */\n protected createOpening(): IDataSourceOpening {\n const refuse = (member: string): never =>\n NotSupportedUtility.throwNotSupported({\n scope: this.constructor.name,\n feature: `opening.${member}`,\n logger: this.logger,\n });\n\n return {\n getConnector: () => refuse('getConnector'),\n getClient: () => refuse('getClient'),\n beginTransaction: () => Promise.resolve().then(() => refuse('beginTransaction')),\n };\n }\n\n /**\n * The boot's replacement for `configure()` on a datasource that opens on first use: records the options and opens nothing.\n * Refused for a family that cannot honour it.\n */\n deferOpen(opts: { options?: ConfigurableOptions }): void {\n if (!this.supportsDeferredOpen()) {\n throw getError({\n message: `[${this.constructor.name}][deferOpen] open: 'first-use' is not supported by this datasource family | Use open: { on: 'start' }, or remove the option`,\n });\n }\n\n this.deferredOptions = opts.options;\n }\n\n /**\n * Resolves once the datasource is open. At once for one that opens with the application. Otherwise the first caller\n * starts `configure()` and the rest await the same promise, so it runs once; a failure rejects all of them, undoes what the\n * failed `configure()` left ({@link discardPartialOpen}) and clears the slot, so the next call opens afresh. After\n * `close()` it rejects: a stopped application does not reopen its datasources.\n */\n ensureOpen(): Promise<void> {\n if (!this.isOpenDeferred()) {\n return Promise.resolve();\n }\n\n // Closed first: a call after `close()` is told so, whether or not the datasource had been opened.\n if (this.isShutDown) {\n return Promise.reject(\n getError({\n message: `[${this.constructor.name}][ensureOpen] The datasource is closed | It opens on first use only before close()`,\n }),\n );\n }\n\n if (this.isOpened) {\n return Promise.resolve();\n }\n\n if (this.abandoned) {\n return Promise.reject(\n getError({\n message: `[${this.constructor.name}][ensureOpen] The previous open is still running after its timeout | It is retried once it has settled`,\n }),\n );\n }\n\n this.opening ??= this.runOpen();\n\n return this.opening;\n }\n\n private async runOpen(): Promise<void> {\n const timeoutMs = this.getOpenTimeoutMs();\n const work = Promise.resolve().then(() =>\n this.configure(this.deferredOptions, this.createOpening()),\n );\n let timer: ReturnType<typeof setTimeout> | undefined;\n const expired = new Promise<typeof OPEN_TIMED_OUT>((resolve) => {\n if (timeoutMs > 0) {\n timer = setTimeout(() => resolve(OPEN_TIMED_OUT), timeoutMs);\n }\n });\n\n try {\n const outcome = await Promise.race([work.then(() => OPEN_DONE), expired]);\n\n if (outcome === OPEN_TIMED_OUT) {\n this.abandoned = this.settleAbandoned({ work });\n\n throw getError({\n message: `[${this.constructor.name}][ensureOpen] The open did not finish within ${timeoutMs} ms | Does configure() await the datasource (a repository, ensureOpen)? Use the opening argument inside configure()`,\n });\n }\n\n this.isOpened = true;\n } catch (error) {\n await this.discardOpenAttempt();\n\n throw error;\n } finally {\n if (timer !== undefined) {\n clearTimeout(timer);\n }\n\n this.opening = undefined;\n }\n }\n\n /** When an abandoned open finally settles, whatever it built is closed (it was never published) and retries are allowed again. */\n private async settleAbandoned(opts: { work: Promise<unknown> }): Promise<void> {\n try {\n await opts.work;\n // eslint-disable-next-line venizia/no-silent-catch -- the abandoned attempt's own outcome was already reported by the timeout; only its clean-up matters now\n } catch {\n // Falls through to the clean-up.\n }\n\n await this.discardOpenAttempt();\n this.abandoned = undefined;\n }\n\n private async discardOpenAttempt(): Promise<void> {\n try {\n await this.discardPartialOpen();\n // eslint-disable-next-line venizia/no-silent-catch -- the open's own error is what the caller must see: a failed clean-up is logged, never thrown over it\n } catch (cleanupError) {\n this.logger\n .for(this.ensureOpen.name)\n .warn('Clean-up after a failed open also failed | error: %s', cleanupError);\n }\n }\n\n /** Undoes what a `configure()` that threw left behind, so the next open starts clean. The root holds nothing; a family that keeps a client overrides it. */\n protected discardPartialOpen(): ValueOrPromise<void> {}\n\n /**\n * Waits for an open in flight and refuses any later one. A family's `close()` calls it first, so a stop that arrives\n * during the first use closes what that open built instead of racing it.\n */\n protected async settleOpening(): Promise<void> {\n this.isShutDown = true;\n\n try {\n await this.opening;\n // eslint-disable-next-line venizia/no-silent-catch -- the failed open was reported to its own waiters; stopping goes on\n } catch (openError) {\n this.logger\n .for(this.close.name)\n .debug('The open in flight failed while stopping | error: %s', openError);\n }\n }\n\n getSettings() {\n return this.settings;\n }\n\n getSchema(): Schema {\n if (!this.schema) {\n throw getError({\n message: `[${this.constructor.name}] Schema not initialized. Override getSchema() or provide schema in constructor.`,\n });\n }\n\n return this.schema;\n }\n\n /** Capability probe, overridden by connectors that support it (e.g. postgres reports `{ transactions: true }`). */\n getCapabilities(): IDataSourceCapabilities {\n return { transactions: false };\n }\n\n /** Nothing to release at this root; a family that holds a connection overrides it. */\n close(): Promise<void> {\n return Promise.resolve();\n }\n\n /** Defaults to throwing NotSupported - only connectors with real transaction support override this; async so callers get a rejected promise, not a synchronous throw that skips try/catch. */\n async beginTransaction(_opts?: ITransactionOptions): Promise<ITransaction> {\n return NotSupportedUtility.throwNotSupported({\n scope: this.constructor.name,\n feature: 'Transactions',\n logger: this.logger,\n });\n }\n\n /** Model classes bound to this datasource via `@repository` metadata - paradigm-free (no schema/relation resolution). */\n protected getBoundModelClasses(): Array<TClass<unknown>> {\n return MetadataRegistry.getInstance().getModelClasses({\n dataSource: this.constructor as TClass<IDataSource>,\n });\n }\n\n /** Walks model classes bound to this datasource, reads a connector-specific artifact via `read`, and returns a name-keyed registry - skips undefined reads, throws on duplicate names, honors `autoDiscovery: false`. */\n protected discoverDefinitions<TDefinition extends { name: string }>(opts: {\n read: (modelClass: TClass<unknown>) => TDefinition | undefined;\n kind: string;\n }): Record<string, TDefinition> {\n const { read, kind } = opts;\n const logger = this.logger.for(this.discoverDefinitions.name);\n const registry = MetadataRegistry.getInstance();\n\n const metadata = registry.getDataSourceMetadata({ target: this.constructor });\n\n if (metadata?.autoDiscovery === false) {\n logger.debug('Auto-discovery disabled for %s', this.name);\n\n return {};\n }\n\n const modelClasses = this.getBoundModelClasses();\n\n const definitions: Record<string, TDefinition> = {};\n const definitionOwners = new Map<string, string>();\n\n for (const modelClass of modelClasses) {\n const definition = read(modelClass);\n\n if (!definition) {\n logger.warn(\n 'Model has no %s definition | Skipping | Name: %s | Model: %s',\n kind,\n this.name,\n modelClass.name,\n );\n continue;\n }\n\n const existingOwner = definitionOwners.get(definition.name);\n\n if (existingOwner !== undefined && existingOwner !== modelClass.name) {\n throw getError({\n message: `[${this.constructor.name}][discoverDefinitions] Duplicate ${kind} name '${definition.name}' | Name: ${this.name} | Classes: ${existingOwner}, ${modelClass.name}`,\n });\n }\n\n definitionOwners.set(definition.name, modelClass.name);\n definitions[definition.name] = definition;\n }\n\n const names = Object.keys(definitions);\n logger.debug(\n 'Detected %s(s) | Name: %s | Count: %s | Names: %j',\n kind,\n this.name,\n names.length,\n names,\n );\n\n return definitions;\n }\n}\n"]}
1
+ {"version":3,"file":"abstract.js","sourceRoot":"","sources":["../../../../src/base/datasources/abstract.ts"],"names":[],"mappings":"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","sourcesContent":["import { MetadataRegistry } from '@/helpers/inversion';\nimport type { TClass } from '@venizia/ignis-helpers/common';\nimport { getError } from '@venizia/ignis-helpers/core';\nimport type { IDataSource, TAnyDataSourceSchema, TDataSourceOpenMode } from './common';\nimport { DataSourceOpenDefaults, DataSourceOpenModes } from './common';\nimport { DataSourceRoot } from './root';\n\n/** Engine-neutral datasource root - NO SQL members. Every connector family extends this. */\nexport abstract class AbstractDataSource<\n Settings extends object = {},\n Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,\n ConfigurableOptions extends object = {},\n> extends DataSourceRoot<Settings, Schema, ConfigurableOptions> {\n /** The `open.on` of `@datasource`, `start` when unset. */\n override getOpenMode(): TDataSourceOpenMode {\n const metadata = MetadataRegistry.getInstance().getDataSourceMetadata({\n target: this.constructor,\n });\n\n return metadata?.open?.on ?? DataSourceOpenModes.START;\n }\n\n /** The `open.timeoutMs` of `@datasource` (ms; `0` waits for ever), 60 s when unset. */\n override getOpenTimeoutMs(): number {\n const metadata = MetadataRegistry.getInstance().getDataSourceMetadata({\n target: this.constructor,\n });\n\n return metadata?.open?.timeoutMs ?? DataSourceOpenDefaults.TIMEOUT_MS;\n }\n\n /** Model classes bound to this datasource via `@repository` metadata - paradigm-free (no schema/relation resolution). */\n protected getBoundModelClasses(): Array<TClass<unknown>> {\n return MetadataRegistry.getInstance().getModelClasses({\n dataSource: this.constructor as TClass<IDataSource>,\n });\n }\n\n /** Walks model classes bound to this datasource, reads a connector-specific artifact via `read`, and returns a name-keyed registry - skips undefined reads, throws on duplicate names, honors `autoDiscovery: false`. */\n protected discoverDefinitions<TDefinition extends { name: string }>(opts: {\n read: (modelClass: TClass<unknown>) => TDefinition | undefined;\n kind: string;\n }): Record<string, TDefinition> {\n const { read, kind } = opts;\n const logger = this.logger.for(this.discoverDefinitions.name);\n const registry = MetadataRegistry.getInstance();\n\n const metadata = registry.getDataSourceMetadata({ target: this.constructor });\n\n if (metadata?.autoDiscovery === false) {\n logger.debug('Auto-discovery disabled for %s', this.name);\n\n return {};\n }\n\n const modelClasses = this.getBoundModelClasses();\n\n const definitions: Record<string, TDefinition> = {};\n const definitionOwners = new Map<string, string>();\n\n for (const modelClass of modelClasses) {\n const definition = read(modelClass);\n\n if (!definition) {\n logger.warn(\n 'Model has no %s definition | Skipping | Name: %s | Model: %s',\n kind,\n this.name,\n modelClass.name,\n );\n continue;\n }\n\n const existingOwner = definitionOwners.get(definition.name);\n\n if (existingOwner !== undefined && existingOwner !== modelClass.name) {\n throw getError({\n message: `[${this.constructor.name}][discoverDefinitions] Duplicate ${kind} name '${definition.name}' | Name: ${this.name} | Classes: ${existingOwner}, ${modelClass.name}`,\n });\n }\n\n definitionOwners.set(definition.name, modelClass.name);\n definitions[definition.name] = definition;\n }\n\n const names = Object.keys(definitions);\n logger.debug(\n 'Detected %s(s) | Name: %s | Count: %s | Names: %j',\n kind,\n this.name,\n names.length,\n names,\n );\n\n return definitions;\n }\n}\n"]}
@@ -1,4 +1,4 @@
1
- import type { AnyType, IConfigurable, TClass, TConstValue, ValueOrPromise } from '@venizia/ignis-helpers/common';
1
+ import type { IConfigurable, TClass, TConstValue, ValueOrPromise } from '@venizia/ignis-helpers/common';
2
2
  /** Names of the supported datasource drivers, split into relational and search sets. `isValid` checks a value against all of them. */
3
3
  export declare class DataSourceDrivers {
4
4
  static readonly NODE_POSTGRES = "node-postgres";
@@ -68,7 +68,7 @@ export type TDataSourceDriver = TConstValue<typeof DataSourceDrivers> | (string
68
68
  * package into a bundle - a name string pulls nothing, and a bare side-effect import may be
69
69
  * dropped. Untyped because `IRelationalDriver` lives under `connectors/`, off-limits to `base/`.
70
70
  */
71
- export type TDataSourceDriverClass = TClass<AnyType>;
71
+ export type TDataSourceDriverClass = TClass<unknown>;
72
72
  /** Loose schema record of a datasource; the default `Schema` type argument of `IDataSource`. */
73
73
  export type TAnyDataSourceSchema = Record<string, any>;
74
74
  /** Engine-neutral datasource contract - the root every connector family implements. */
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/base/datasources/common/types.ts"],"names":[],"mappings":"AAQA,sIAAsI;AACtI,MAAM,OAAO,iBAAiB;IAC5B,+FAA+F;aAC/E,kBAAa,GAAG,eAAe,CAAC;aAChC,gBAAW,GAAG,aAAa,CAAC;aAC5B,WAAM,GAAG,QAAQ,CAAC;aAClB,WAAM,GAAG,QAAQ,CAAC;IAElC,SAAS;aACO,cAAS,GAAG,WAAW,CAAC;aACxB,gBAAW,GAAG,aAAa,CAAC;aAE5B,0BAAqB,GAAG,IAAI,GAAG,CAAC;QAC9C,IAAI,CAAC,aAAa;QAClB,IAAI,CAAC,WAAW;QAChB,IAAI,CAAC,MAAM;QACX,IAAI,CAAC,MAAM;KACZ,CAAC,CAAC;aAEa,sBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;aAEhE,eAAU,GAAG,IAAI,GAAG,CAAC;QACnC,aAAa;QACb,IAAI,CAAC,aAAa;QAClB,IAAI,CAAC,WAAW;QAChB,IAAI,CAAC,MAAM;QACX,IAAI,CAAC,MAAM;QAEX,SAAS;QACT,IAAI,CAAC,SAAS;QACd,IAAI,CAAC,WAAW;KACjB,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAGH,6HAA6H;AAC7H,MAAM,OAAO,mBAAmB;aACd,UAAK,GAAG,OAAO,CAAC;aAChB,cAAS,GAAG,WAAW,CAAC;aAExB,eAAU,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAEnE,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAGH,qCAAqC;AACrC,MAAM,OAAO,sBAAsB;IACjC,qKAAqK;aACrJ,eAAU,GAAG,MAAM,CAAC","sourcesContent":["import type {\n AnyType,\n IConfigurable,\n TClass,\n TConstValue,\n ValueOrPromise,\n} from '@venizia/ignis-helpers/common';\n\n/** Names of the supported datasource drivers, split into relational and search sets. `isValid` checks a value against all of them. */\nexport class DataSourceDrivers {\n // Relational - PGlite is a Postgres DRIVER (Postgres compiled to WASM), not a separate engine.\n static readonly NODE_POSTGRES = 'node-postgres';\n static readonly POSTGRES_JS = 'postgres-js';\n static readonly PGLITE = 'pglite';\n static readonly LIBSQL = 'libsql';\n\n // Search\n static readonly TYPESENSE = 'typesense';\n static readonly MEILISEARCH = 'meilisearch';\n\n static readonly RELATIONAL_SCHEME_SET = new Set([\n this.NODE_POSTGRES,\n this.POSTGRES_JS,\n this.PGLITE,\n this.LIBSQL,\n ]);\n\n static readonly SEARCH_SCHEME_SET = new Set([this.TYPESENSE, this.MEILISEARCH]);\n\n static readonly SCHEME_SET = new Set([\n // Relational\n this.NODE_POSTGRES,\n this.POSTGRES_JS,\n this.PGLITE,\n this.LIBSQL,\n\n // Search\n this.TYPESENSE,\n this.MEILISEARCH,\n ]);\n\n static isValid(value: string): boolean {\n return this.SCHEME_SET.has(value);\n }\n}\n\n/** When a datasource opens: with the application (`start`, the default) or at the first call that needs it (`first-use`). */\nexport class DataSourceOpenModes {\n static readonly START = 'start';\n static readonly FIRST_USE = 'first-use';\n\n static readonly SCHEME_SET = new Set([this.START, this.FIRST_USE]);\n\n static isValid(value: string): value is TDataSourceOpenMode {\n return this.SCHEME_SET.has(value);\n }\n}\n\n/** Defaults of the `open` option. */\nexport class DataSourceOpenDefaults {\n /** How long a first use waits for the open before it gives up (ms): a WASM boot on a slow link fits, a `configure()` that waits on itself does not hang for ever. */\n static readonly TIMEOUT_MS = 60_000;\n}\n\n/** One of the {@link DataSourceOpenModes} values. */\nexport type TDataSourceOpenMode = TConstValue<typeof DataSourceOpenModes>;\n\n/** The `open` option of `@datasource`. */\nexport interface IDataSourceOpenOptions {\n /**\n * `start`: `configure()` runs when the application starts, and `listen()` waits for it. `first-use`: the application\n * starts without opening the datasource; the first call that needs it runs `configure()` once, and every call that\n * arrives meanwhile waits for that one open. A failed open rejects every waiting call, leaves nothing half-open, and is\n * tried again by the next call.\n *\n * @default 'start'\n */\n on?: TDataSourceOpenMode;\n\n /**\n * `first-use` only: how long the open may take (ms) before every waiting call is rejected with a named error and the\n * attempt is abandoned. An abandoned `configure()` that finishes later is closed and never published, and the next call\n * waits until it has settled before trying again. `0` waits for ever.\n *\n * @default 60000\n */\n timeoutMs?: number;\n}\n\n/**\n * What `configure()` is given to do its database work while the datasource is opening: the connector, the client and a\n * transaction, through the datasource's own ungated internals. Only `configure()` receives it, so nothing outside can use it\n * and every other caller still waits for the open to finish. Generic over the datasource's connector, client and\n * transaction types, so `opening.getClient()` of a PGlite datasource is a `PGlite`.\n *\n * Inside the open of a datasource that opens on first use, the public `getConnector()`, `getClient()` and\n * `beginTransaction()` are gated (they wait for the open, which waits for `configure()`), and a repository cannot be used:\n * use these handles instead.\n */\nexport interface IDataSourceOpening<\n TConnector = unknown,\n Client = unknown,\n TTransaction extends ITransaction = ITransaction,\n TTransactionOptions extends ITransactionOptions = ITransactionOptions,\n> {\n getConnector(): TConnector;\n getClient(): Client;\n beginTransaction(opts?: TTransactionOptions): Promise<TTransaction>;\n}\n\n// `(string & {})` keeps autocomplete for the known values\n// while still accepting any other engine-driver string.\n/** A driver name: one of `DataSourceDrivers`, or any other string for an unlisted engine. */\nexport type TDataSourceDriver = TConstValue<typeof DataSourceDrivers> | (string & {});\n\n/**\n * A driver CLASS, named by `@datasource({ driver })`. The class reference is what pulls the peer\n * package into a bundle - a name string pulls nothing, and a bare side-effect import may be\n * dropped. Untyped because `IRelationalDriver` lives under `connectors/`, off-limits to `base/`.\n */\nexport type TDataSourceDriverClass = TClass<AnyType>;\n\n/** Loose schema record of a datasource; the default `Schema` type argument of `IDataSource`. */\nexport type TAnyDataSourceSchema = Record<string, any>;\n\n/** Engine-neutral datasource contract - the root every connector family implements. */\nexport interface IDataSource<\n Settings extends object = {},\n Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,\n ConfigurableOptions extends object = {},\n> extends IConfigurable<ConfigurableOptions> {\n name: string;\n settings: Settings;\n schema: Schema;\n\n getSettings(): Settings;\n getSchema(): Schema;\n\n /** Releases what `configure()` opened. `stop()` calls it on every datasource the boot configured. */\n close?(): Promise<void>;\n\n /** The datasource's own `configure()` receives the handles of {@link IDataSourceOpening} as its second argument. */\n configure(opts?: ConfigurableOptions, opening?: IDataSourceOpening): ValueOrPromise<void>;\n\n /** True when the datasource opens on first use (`@datasource({ open: { on: 'first-use' } })`): the boot then calls {@link deferOpen} instead of `configure()`. */\n isOpenDeferred?(): boolean;\n\n /** Records the options `configure()` will get when the datasource opens on first use; nothing is opened. */\n deferOpen?(opts: { options?: ConfigurableOptions }): void;\n\n /** Resolves once the datasource is open: at once when it opens with the application or is already open, else after the one open that the first use starts. */\n ensureOpen?(): Promise<void>;\n}\n\n/**\n * Neutral transaction options - isolation levels are engine vocabulary, so `isolationLevel` stays\n * a loose string here and connectors narrow it in their own `ITransactionOptions` extension.\n */\nexport interface ITransactionOptions {\n isolationLevel?: string;\n}\n\n/** Neutral transaction handle - the minimum shape every connector's transaction satisfies. */\nexport interface ITransaction {\n isActive: boolean;\n commit(): Promise<void>;\n rollback(): Promise<void>;\n}\n\n/** What a datasource supports. `transactions` tells whether it can open transactions. */\nexport interface IDataSourceCapabilities {\n transactions: boolean;\n}\n\n/** Capabilities of a search datasource. Each `search` flag tells whether the engine supports that feature. */\nexport interface ISearchableDataSourceCapabilities extends IDataSourceCapabilities {\n search?: {\n /** Vector / semantic / hybrid search (search engines). */\n vector?: boolean;\n\n /** Batched multi-query search across collections. */\n multi?: boolean;\n\n /** Merged (union) result set across a multi-search. */\n union?: boolean;\n\n /** Synonym sets (multi-way / one-way). */\n synonyms?: boolean;\n };\n}\n"]}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../../src/base/datasources/common/types.ts"],"names":[],"mappings":"AAOA,sIAAsI;AACtI,MAAM,OAAO,iBAAiB;IAC5B,+FAA+F;aAC/E,kBAAa,GAAG,eAAe,CAAC;aAChC,gBAAW,GAAG,aAAa,CAAC;aAC5B,WAAM,GAAG,QAAQ,CAAC;aAClB,WAAM,GAAG,QAAQ,CAAC;IAElC,SAAS;aACO,cAAS,GAAG,WAAW,CAAC;aACxB,gBAAW,GAAG,aAAa,CAAC;aAE5B,0BAAqB,GAAG,IAAI,GAAG,CAAC;QAC9C,IAAI,CAAC,aAAa;QAClB,IAAI,CAAC,WAAW;QAChB,IAAI,CAAC,MAAM;QACX,IAAI,CAAC,MAAM;KACZ,CAAC,CAAC;aAEa,sBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;aAEhE,eAAU,GAAG,IAAI,GAAG,CAAC;QACnC,aAAa;QACb,IAAI,CAAC,aAAa;QAClB,IAAI,CAAC,WAAW;QAChB,IAAI,CAAC,MAAM;QACX,IAAI,CAAC,MAAM;QAEX,SAAS;QACT,IAAI,CAAC,SAAS;QACd,IAAI,CAAC,WAAW;KACjB,CAAC,CAAC;IAEH,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAGH,6HAA6H;AAC7H,MAAM,OAAO,mBAAmB;aACd,UAAK,GAAG,OAAO,CAAC;aAChB,cAAS,GAAG,WAAW,CAAC;aAExB,eAAU,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IAEnE,MAAM,CAAC,OAAO,CAAC,KAAa;QAC1B,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;;AAGH,qCAAqC;AACrC,MAAM,OAAO,sBAAsB;IACjC,qKAAqK;aACrJ,eAAU,GAAG,MAAM,CAAC","sourcesContent":["import type {\n IConfigurable,\n TClass,\n TConstValue,\n ValueOrPromise,\n} from '@venizia/ignis-helpers/common';\n\n/** Names of the supported datasource drivers, split into relational and search sets. `isValid` checks a value against all of them. */\nexport class DataSourceDrivers {\n // Relational - PGlite is a Postgres DRIVER (Postgres compiled to WASM), not a separate engine.\n static readonly NODE_POSTGRES = 'node-postgres';\n static readonly POSTGRES_JS = 'postgres-js';\n static readonly PGLITE = 'pglite';\n static readonly LIBSQL = 'libsql';\n\n // Search\n static readonly TYPESENSE = 'typesense';\n static readonly MEILISEARCH = 'meilisearch';\n\n static readonly RELATIONAL_SCHEME_SET = new Set([\n this.NODE_POSTGRES,\n this.POSTGRES_JS,\n this.PGLITE,\n this.LIBSQL,\n ]);\n\n static readonly SEARCH_SCHEME_SET = new Set([this.TYPESENSE, this.MEILISEARCH]);\n\n static readonly SCHEME_SET = new Set([\n // Relational\n this.NODE_POSTGRES,\n this.POSTGRES_JS,\n this.PGLITE,\n this.LIBSQL,\n\n // Search\n this.TYPESENSE,\n this.MEILISEARCH,\n ]);\n\n static isValid(value: string): boolean {\n return this.SCHEME_SET.has(value);\n }\n}\n\n/** When a datasource opens: with the application (`start`, the default) or at the first call that needs it (`first-use`). */\nexport class DataSourceOpenModes {\n static readonly START = 'start';\n static readonly FIRST_USE = 'first-use';\n\n static readonly SCHEME_SET = new Set([this.START, this.FIRST_USE]);\n\n static isValid(value: string): value is TDataSourceOpenMode {\n return this.SCHEME_SET.has(value);\n }\n}\n\n/** Defaults of the `open` option. */\nexport class DataSourceOpenDefaults {\n /** How long a first use waits for the open before it gives up (ms): a WASM boot on a slow link fits, a `configure()` that waits on itself does not hang for ever. */\n static readonly TIMEOUT_MS = 60_000;\n}\n\n/** One of the {@link DataSourceOpenModes} values. */\nexport type TDataSourceOpenMode = TConstValue<typeof DataSourceOpenModes>;\n\n/** The `open` option of `@datasource`. */\nexport interface IDataSourceOpenOptions {\n /**\n * `start`: `configure()` runs when the application starts, and `listen()` waits for it. `first-use`: the application\n * starts without opening the datasource; the first call that needs it runs `configure()` once, and every call that\n * arrives meanwhile waits for that one open. A failed open rejects every waiting call, leaves nothing half-open, and is\n * tried again by the next call.\n *\n * @default 'start'\n */\n on?: TDataSourceOpenMode;\n\n /**\n * `first-use` only: how long the open may take (ms) before every waiting call is rejected with a named error and the\n * attempt is abandoned. An abandoned `configure()` that finishes later is closed and never published, and the next call\n * waits until it has settled before trying again. `0` waits for ever.\n *\n * @default 60000\n */\n timeoutMs?: number;\n}\n\n/**\n * What `configure()` is given to do its database work while the datasource is opening: the connector, the client and a\n * transaction, through the datasource's own ungated internals. Only `configure()` receives it, so nothing outside can use it\n * and every other caller still waits for the open to finish. Generic over the datasource's connector, client and\n * transaction types, so `opening.getClient()` of a PGlite datasource is a `PGlite`.\n *\n * Inside the open of a datasource that opens on first use, the public `getConnector()`, `getClient()` and\n * `beginTransaction()` are gated (they wait for the open, which waits for `configure()`), and a repository cannot be used:\n * use these handles instead.\n */\nexport interface IDataSourceOpening<\n TConnector = unknown,\n Client = unknown,\n TTransaction extends ITransaction = ITransaction,\n TTransactionOptions extends ITransactionOptions = ITransactionOptions,\n> {\n getConnector(): TConnector;\n getClient(): Client;\n beginTransaction(opts?: TTransactionOptions): Promise<TTransaction>;\n}\n\n// `(string & {})` keeps autocomplete for the known values\n// while still accepting any other engine-driver string.\n/** A driver name: one of `DataSourceDrivers`, or any other string for an unlisted engine. */\nexport type TDataSourceDriver = TConstValue<typeof DataSourceDrivers> | (string & {});\n\n/**\n * A driver CLASS, named by `@datasource({ driver })`. The class reference is what pulls the peer\n * package into a bundle - a name string pulls nothing, and a bare side-effect import may be\n * dropped. Untyped because `IRelationalDriver` lives under `connectors/`, off-limits to `base/`.\n */\nexport type TDataSourceDriverClass = TClass<unknown>;\n\n/** Loose schema record of a datasource; the default `Schema` type argument of `IDataSource`. */\nexport type TAnyDataSourceSchema = Record<string, any>;\n\n/** Engine-neutral datasource contract - the root every connector family implements. */\nexport interface IDataSource<\n Settings extends object = {},\n Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema,\n ConfigurableOptions extends object = {},\n> extends IConfigurable<ConfigurableOptions> {\n name: string;\n settings: Settings;\n schema: Schema;\n\n getSettings(): Settings;\n getSchema(): Schema;\n\n /** Releases what `configure()` opened. `stop()` calls it on every datasource the boot configured. */\n close?(): Promise<void>;\n\n /** The datasource's own `configure()` receives the handles of {@link IDataSourceOpening} as its second argument. */\n configure(opts?: ConfigurableOptions, opening?: IDataSourceOpening): ValueOrPromise<void>;\n\n /** True when the datasource opens on first use (`@datasource({ open: { on: 'first-use' } })`): the boot then calls {@link deferOpen} instead of `configure()`. */\n isOpenDeferred?(): boolean;\n\n /** Records the options `configure()` will get when the datasource opens on first use; nothing is opened. */\n deferOpen?(opts: { options?: ConfigurableOptions }): void;\n\n /** Resolves once the datasource is open: at once when it opens with the application or is already open, else after the one open that the first use starts. */\n ensureOpen?(): Promise<void>;\n}\n\n/**\n * Neutral transaction options - isolation levels are engine vocabulary, so `isolationLevel` stays\n * a loose string here and connectors narrow it in their own `ITransactionOptions` extension.\n */\nexport interface ITransactionOptions {\n isolationLevel?: string;\n}\n\n/** Neutral transaction handle - the minimum shape every connector's transaction satisfies. */\nexport interface ITransaction {\n isActive: boolean;\n commit(): Promise<void>;\n rollback(): Promise<void>;\n}\n\n/** What a datasource supports. `transactions` tells whether it can open transactions. */\nexport interface IDataSourceCapabilities {\n transactions: boolean;\n}\n\n/** Capabilities of a search datasource. Each `search` flag tells whether the engine supports that feature. */\nexport interface ISearchableDataSourceCapabilities extends IDataSourceCapabilities {\n search?: {\n /** Vector / semantic / hybrid search (search engines). */\n vector?: boolean;\n\n /** Batched multi-query search across collections. */\n multi?: boolean;\n\n /** Merged (union) result set across a multi-search. */\n union?: boolean;\n\n /** Synonym sets (multi-way / one-way). */\n synonyms?: boolean;\n };\n}\n"]}
@@ -1,3 +1,4 @@
1
1
  export * from './abstract.js';
2
+ export * from './root.js';
2
3
  export * from './common/index.js';
3
4
  //# sourceMappingURL=index.d.ts.map
@@ -1,3 +1,4 @@
1
1
  export * from './abstract.js';
2
+ export * from './root.js';
2
3
  export * from './common/index.js';
3
4
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/datasources/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC","sourcesContent":["export * from './abstract';\nexport * from './common';\n"]}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/base/datasources/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC","sourcesContent":["export * from './abstract';\nexport * from './root';\nexport * from './common';\n"]}
@@ -0,0 +1,107 @@
1
+ import type { TClass, ValueOrPromise } from '@venizia/ignis-helpers/common';
2
+ import { BaseHelper } from '@venizia/ignis-helpers/core';
3
+ import type { IDataSource, IDataSourceCapabilities, IDataSourceOpening, ITransaction, ITransactionOptions, TAnyDataSourceSchema, TDataSourceOpenMode } from './common/index.js';
4
+ import { OPENING_HANDLES } from './opening-handles.js';
5
+ /**
6
+ * Brands the datasource root so `@repository` can recognise a subclass WITHOUT `instanceof`.
7
+ *
8
+ * Two copies of this package give two `DataSourceRoot` classes, and `instanceof` across them is
9
+ * false - the same trap `isApplicationError` exists to avoid for `ApplicationError`. `Symbol.for` is
10
+ * realm-keyed, so both copies produce this exact symbol, and a static is inherited by every
11
+ * subclass however deep.
12
+ */
13
+ /**
14
+ * The key keeps its old name, `abstract-data-source`, so a copy of the package from before `DataSourceRoot` still recognises the
15
+ * classes of a newer one, and the other way round.
16
+ */
17
+ export declare const DATA_SOURCE_BRAND: unique symbol;
18
+ /** True for `DataSourceRoot` itself and for any class extending it (`AbstractDataSource` among them), across package copies. */
19
+ export declare const isDataSourceClass: (value: unknown) => value is TClass<unknown>;
20
+ /**
21
+ * The datasource root with no dependency-injection import: the brand, the settings, the open-on-first-use state machine
22
+ * and the no-op defaults. A client that only talks HTTP extends this, so a browser bundle does not carry the metadata
23
+ * registry; {@link AbstractDataSource} adds what reads `@datasource` and `@repository` metadata.
24
+ */
25
+ export declare abstract class DataSourceRoot<Settings extends object = {}, Schema extends TAnyDataSourceSchema = TAnyDataSourceSchema, ConfigurableOptions extends object = {}> extends BaseHelper implements IDataSource<Settings, Schema, ConfigurableOptions> {
26
+ /** Read by {@link isDataSourceClass}. Static, so every subclass inherits it. */
27
+ static readonly [DATA_SOURCE_BRAND] = true;
28
+ name: string;
29
+ settings: Settings;
30
+ schema: Schema;
31
+ abstract configure(opts?: ConfigurableOptions, opening?: IDataSourceOpening): ValueOrPromise<void>;
32
+ /** The options the boot would have given `configure()`, kept for the open that the first use starts. */
33
+ private deferredOptions?;
34
+ /** The open in flight: every call that arrives meanwhile awaits this one promise. */
35
+ private opening?;
36
+ /**
37
+ * An open that outlived its timeout and has not settled. Nothing is retried until it has: two `configure()` must never
38
+ * run at once, and when it does settle what it built is closed, never published.
39
+ */
40
+ private abandoned?;
41
+ private isOpened;
42
+ private isShutDown;
43
+ /**
44
+ * Whether this family can open on first use: only a family whose every entry point first awaits {@link ensureOpen}
45
+ * says yes (the relational one does). A family that does not is refused at boot rather than left half-working.
46
+ */
47
+ protected supportsDeferredOpen(): boolean;
48
+ /** How the datasource opens: `start` here. {@link AbstractDataSource} reads the `open.on` of `@datasource`. */
49
+ getOpenMode(): TDataSourceOpenMode;
50
+ isOpenDeferred(): boolean;
51
+ /** How long an open may take (ms; `0` waits for ever): 60 s here. {@link AbstractDataSource} reads the `open.timeoutMs` of `@datasource`. */
52
+ getOpenTimeoutMs(): number;
53
+ /**
54
+ * Whether the datasource is open. One that opens on first use: after the first use has finished, until `close()`. One that
55
+ * opens at start: from the moment the application has started it, until `close()`.
56
+ */
57
+ isOpen(): boolean;
58
+ /** Whether the first use is opening the datasource right now. */
59
+ isOpening(): boolean;
60
+ /** Whether `close()` has begun. A datasource that opens on first use is not reopened after it. */
61
+ isClosed(): boolean;
62
+ /**
63
+ * What the application boot calls to get the handles it passes to `configure()` of a datasource that opens at start. Keyed by a
64
+ * symbol the package does not export, so nothing else can obtain the handles: see {@link OPENING_HANDLES}.
65
+ */
66
+ [OPENING_HANDLES](): IDataSourceOpening;
67
+ /**
68
+ * The handles `configure()` gets as its second argument, in both modes. The root has no connector, client or transaction to
69
+ * hand out; a family that has them overrides this. Protected: the only ways out are the argument of `configure()` and the
70
+ * boot's private key.
71
+ */
72
+ protected createOpening(): IDataSourceOpening;
73
+ /**
74
+ * The boot's replacement for `configure()` on a datasource that opens on first use: records the options and opens nothing.
75
+ * Refused for a family that cannot honour it.
76
+ */
77
+ deferOpen(opts: {
78
+ options?: ConfigurableOptions;
79
+ }): void;
80
+ /**
81
+ * Resolves once the datasource is open. At once for one that opens with the application. Otherwise the first caller
82
+ * starts `configure()` and the rest await the same promise, so it runs once; a failure rejects all of them, undoes what the
83
+ * failed `configure()` left ({@link discardPartialOpen}) and clears the slot, so the next call opens afresh. After
84
+ * `close()` it rejects: a stopped application does not reopen its datasources.
85
+ */
86
+ ensureOpen(): Promise<void>;
87
+ private runOpen;
88
+ /** When an abandoned open finally settles, whatever it built is closed (it was never published) and retries are allowed again. */
89
+ private settleAbandoned;
90
+ private discardOpenAttempt;
91
+ /** Undoes what a `configure()` that threw left behind, so the next open starts clean. The root holds nothing; a family that keeps a client overrides it. */
92
+ protected discardPartialOpen(): ValueOrPromise<void>;
93
+ /**
94
+ * Waits for an open in flight and refuses any later one. A family's `close()` calls it first, so a stop that arrives
95
+ * during the first use closes what that open built instead of racing it.
96
+ */
97
+ protected settleOpening(): Promise<void>;
98
+ getSettings(): Settings;
99
+ getSchema(): Schema;
100
+ /** Capability probe, overridden by connectors that support it (e.g. postgres reports `{ transactions: true }`). */
101
+ getCapabilities(): IDataSourceCapabilities;
102
+ /** Nothing to release at this root; a family that holds a connection overrides it. */
103
+ close(): Promise<void>;
104
+ /** Defaults to throwing NotSupported - only connectors with real transaction support override this; async so callers get a rejected promise, not a synchronous throw that skips try/catch. */
105
+ beginTransaction(_opts?: ITransactionOptions): Promise<ITransaction>;
106
+ }
107
+ //# sourceMappingURL=root.d.ts.map