@nestjs-transactional/core 1.0.0-alpha.0

package/dist/manager/adapter.registry.js

@@ -0,0 +1,179 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var AdapterRegistry_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdapterRegistry = exports.ADAPTER_REGISTRY = void 0;
+const common_1 = require("@nestjs/common");
+const errors_1 = require("../types/errors");
+/**
+ * DI token for the {@link AdapterRegistry}. Consumers who need to register
+ * adapters manually (for example, integration tests or custom modules)
+ * can inject this token and call {@link AdapterRegistry.register}.
+ */
+exports.ADAPTER_REGISTRY = Symbol('ADAPTER_REGISTRY');
+/**
+ * In-memory registry of {@link TransactionAdapter} instances, keyed by
+ * `(adapterName, instanceName)`. Each adapter type (e.g. `'typeorm'`) may
+ * have multiple instances (e.g. `'primary'`, `'billing'`) — the registry
+ * keeps them separate so that `@Transactional({ adapterInstance: 'billing' })`
+ * can target a specific one.
+ *
+ * The first adapter registered becomes the default; any later registration
+ * can override the default by passing `isDefault = true`.
+ *
+ * Implementation note: the internal key format is `${adapterName}:${instanceName}`.
+ * Neither `adapterName` nor `instanceName` may contain `:` — enforced by
+ * convention, not at runtime.
+ */
+let AdapterRegistry = AdapterRegistry_1 = class AdapterRegistry {
+    adapters = new Map();
+    defaultAdapterName = null;
+    defaultInstanceName = 'default';
+    /**
+     * Register an adapter under `(registration.adapterName, registration.instanceName)`.
+     *
+     * The first registration always becomes the default. Passing
+     * `isDefault = true` on any later registration switches the default to it.
+     *
+     * Re-registering the same pair overwrites the previously stored adapter;
+     * the default pointer is left unchanged unless `isDefault = true` is set.
+     */
+    register(registration, isDefault = false) {
+        const key = AdapterRegistry_1.keyFor(registration.adapterName, registration.instanceName);
+        this.adapters.set(key, registration.adapter);
+        if (isDefault || this.defaultAdapterName === null) {
+            this.defaultAdapterName = registration.adapterName;
+            this.defaultInstanceName = registration.instanceName;
+        }
+    }
+    /**
+     * Look up an adapter by `(adapterName, instanceName)`.
+     *
+     * @throws {TransactionAdapterNotFoundError} If no adapter is registered
+     *   under that pair.
+     */
+    get(adapterName, instanceName) {
+        const adapter = this.adapters.get(AdapterRegistry_1.keyFor(adapterName, instanceName));
+        if (adapter === undefined) {
+            throw new errors_1.TransactionAdapterNotFoundError(adapterName, instanceName);
+        }
+        return adapter;
+    }
+    /**
+     * Look up an adapter by its public dataSource name (DD-020). Iterates
+     * the registered entries and returns the one whose `instanceName`
+     * matches `dataSource` — there is exactly one per dataSource by
+     * convention.
+     *
+     * If multiple registrations share the same `instanceName` across
+     * different adapter types (e.g. `typeorm:billing` AND
+     * `prisma:billing`), throws — that configuration is ambiguous and
+     * the user must disambiguate via the `adapter` + `adapterInstance`
+     * options instead.
+     *
+     * @throws {IllegalTransactionStateError} If two or more adapters share
+     *   the same dataSource name.
+     * @throws {TransactionAdapterNotFoundError} If no adapter is registered
+     *   under this dataSource.
+     */
+    getByDataSource(dataSource) {
+        const matches = [];
+        for (const [key, adapter] of this.adapters) {
+            const colon = key.indexOf(':');
+            const adapterName = key.slice(0, colon);
+            const instanceName = key.slice(colon + 1);
+            if (instanceName === dataSource) {
+                matches.push({ adapterName, adapter });
+            }
+        }
+        if (matches.length === 0) {
+            throw new errors_1.TransactionAdapterNotFoundError('*', dataSource);
+        }
+        if (matches.length > 1) {
+            const names = matches.map((m) => `${m.adapterName}:${dataSource}`).join(', ');
+            throw new errors_1.IllegalTransactionStateError(`Multiple adapters registered for dataSource '${dataSource}' (${names}). ` +
+                `Use the explicit \`adapter\` + \`adapterInstance\` options to disambiguate.`);
+        }
+        // Length is exactly 1 here (checked above) — non-null is provably safe.
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        return matches[0].adapter;
+    }
+    /**
+     * Find the adapter type name (`'typeorm'`, `'prisma'`, ...) registered
+     * under the given dataSource. Used by the manager to compose the
+     * composite Map key when only the dataSource name is known.
+     *
+     * Same disambiguation rules as {@link getByDataSource}.
+     */
+    getAdapterNameByDataSource(dataSource) {
+        const matches = [];
+        for (const key of this.adapters.keys()) {
+            const colon = key.indexOf(':');
+            const adapterName = key.slice(0, colon);
+            const instanceName = key.slice(colon + 1);
+            if (instanceName === dataSource) {
+                matches.push(adapterName);
+            }
+        }
+        if (matches.length === 0) {
+            throw new errors_1.TransactionAdapterNotFoundError('*', dataSource);
+        }
+        if (matches.length > 1) {
+            const names = matches.map((n) => `${n}:${dataSource}`).join(', ');
+            throw new errors_1.IllegalTransactionStateError(`Multiple adapters registered for dataSource '${dataSource}' (${names}). ` +
+                `Use the explicit \`adapter\` + \`adapterInstance\` options to disambiguate.`);
+        }
+        // Length is exactly 1 here (checked above) — non-null is provably safe.
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        return matches[0];
+    }
+    /**
+     * Return the name of the adapter type currently marked default.
+     *
+     * @throws {IllegalTransactionStateError} If no adapter has been registered
+     *   yet — there is no default to choose.
+     */
+    getDefaultAdapterName() {
+        if (this.defaultAdapterName === null) {
+            throw new errors_1.IllegalTransactionStateError('No default adapter registered. Register at least one adapter via ' +
+                'TypeOrmTransactionalModule.forFeature() or the corresponding ' +
+                'transactional module for your ORM.');
+        }
+        return this.defaultAdapterName;
+    }
+    /**
+     * Return the name of the default adapter instance. Defaults to `'default'`
+     * before any adapter is registered — matches the common convention in
+     * per-ORM `forFeature({ instanceName: 'default' })` helpers.
+     */
+    getDefaultInstanceName() {
+        return this.defaultInstanceName;
+    }
+    /**
+     * Return every registration as a new array. Used by bootstrap and
+     * observability code to enumerate configured adapters at runtime.
+     */
+    getAll() {
+        return Array.from(this.adapters.entries(), ([key, adapter]) => {
+            const colon = key.indexOf(':');
+            return {
+                adapterName: key.slice(0, colon),
+                instanceName: key.slice(colon + 1),
+                adapter,
+            };
+        });
+    }
+    static keyFor(adapterName, instanceName) {
+        return `${adapterName}:${instanceName}`;
+    }
+};
+exports.AdapterRegistry = AdapterRegistry;
+exports.AdapterRegistry = AdapterRegistry = AdapterRegistry_1 = __decorate([
+    (0, common_1.Injectable)()
+], AdapterRegistry);
+//# sourceMappingURL=adapter.registry.js.map

package/dist/manager/adapter.registry.js.map

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

package/dist/manager/transaction.manager.d.ts

@@ -0,0 +1,129 @@
+import { type TransactionObserver } from '../observability/transaction-observer';
+import type { ExtendedTransactionOptions } from '../types/transaction-options';
+import { AdapterRegistry } from './adapter.registry';
+/**
+ * Runtime that executes a callback inside a transaction, following the
+ * requested {@link PropagationMode}. Exposes registration points for
+ * before/after-commit and after-rollback hooks that the surrounding
+ * transaction fires at the appropriate phase.
+ *
+ * All seven Spring-compatible propagation modes are supported:
+ * `REQUIRED`, `REQUIRES_NEW`, `NESTED`, `SUPPORTS`, `NOT_SUPPORTED`,
+ * `NEVER`, `MANDATORY`. See {@link TransactionManager.run} for the
+ * per-mode behaviour.
+ */
+export declare class TransactionManager {
+    private readonly registry;
+    private readonly observers;
+    private readonly logger;
+    constructor(registry: AdapterRegistry, observers?: readonly TransactionObserver[]);
+    /**
+     * Execute `fn` inside a transaction managed by the adapter resolved from
+     * `options` (or defaults from {@link AdapterRegistry}).
+     *
+     * Behaviour by propagation mode:
+     * - `REQUIRED` (default): join the active transaction for this adapter
+     *   instance if one exists; otherwise start a new transaction.
+     * - `REQUIRES_NEW`: always start a new, independent transaction. If an
+     *   outer transaction is active, its {@link ActiveTransaction} entry is
+     *   suspended out of the context Map for the duration of the inner call
+     *   and restored afterwards.
+     * - `NESTED`: if an outer transaction is active, run inside a savepoint
+     *   on that transaction (via {@link TransactionAdapter.runInSavepoint}).
+     *   A savepoint rollback leaves the outer transaction intact. Lifecycle
+     *   hooks registered inside a `NESTED` block attach to the outer
+     *   transaction and fire on the outer commit/rollback. If no outer
+     *   transaction is active, `NESTED` degrades to `REQUIRED`.
+     * - `SUPPORTS`: run `fn` in the outer transaction if present; otherwise
+     *   run `fn` directly with no transaction and no lifecycle hooks.
+     * - `NOT_SUPPORTED`: suspend the outer transaction (remove its entry
+     *   from the context Map) and run `fn` without transactional context.
+     *   Restore on return. Note that the adapter-level connection/query
+     *   runner is NOT actually suspended — this is a context-level opt-out.
+     * - `NEVER`: throw {@link IllegalTransactionStateError} if an outer
+     *   transaction is active; otherwise run `fn` directly.
+     * - `MANDATORY`: throw {@link IllegalTransactionStateError} if no outer
+     *   transaction is active; otherwise join it.
+     *
+     * Both inner and outer transactions share the surrounding
+     * {@link TransactionContext} store — same `correlationId`, same Map —
+     * only the Map slot at `instanceName` is swapped as propagation requires.
+     */
+    run<T>(options: ExtendedTransactionOptions, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Compose the {@link TransactionContext} key for a given adapter
+     * (type name) + instance pair. Manager and helper packages must agree
+     * on this format so that `@nestjs-transactional/typeorm`'s
+     * `getCurrentEntityManager` can find the transaction registered here.
+     */
+    private static contextKey;
+    /**
+     * Translate the user-facing options into the internal `(adapterName,
+     * instanceName)` pair used to build the active-transaction Map key.
+     *
+     * Resolution order (DD-020):
+     * 1. `options.dataSource` set: lookup the unique adapter via the
+     *    registry by dataSource name. The dataSource name becomes the
+     *    `instanceName`; the registry hands back the adapter type.
+     * 2. Else: legacy path — `options.adapter` / `options.adapterInstance`
+     *    fall back to the registry's defaults.
+     */
+    private resolveAdapterIdentifiers;
+    /**
+     * Register a hook to fire after the current transaction commits
+     * successfully. Attaches to the first active transaction on the current
+     * async context — sufficient for single-adapter setups. Hook errors are
+     * swallowed with a warning and do not reject `run()`.
+     *
+     * @throws {IllegalTransactionStateError} If called outside an active transaction.
+     */
+    registerAfterCommit(hook: () => Promise<void>): void;
+    /**
+     * Register a hook to fire after the current transaction rolls back. The
+     * hook receives the error that caused the rollback.
+     *
+     * @throws {IllegalTransactionStateError} If called outside an active transaction.
+     */
+    registerAfterRollback(hook: (error: unknown) => Promise<void>): void;
+    /**
+     * Register a hook to fire just before the transaction commits. A throwing
+     * hook triggers the adapter's rollback — the transaction does not commit.
+     *
+     * @throws {IllegalTransactionStateError} If called outside an active transaction.
+     */
+    registerBeforeCommit(hook: () => Promise<void>): void;
+    private startNew;
+    private notifyStart;
+    private notifyCommit;
+    private notifyRollback;
+    /**
+     * Run `fn` inside a savepoint on `parent.handle`. Used by
+     * {@link PropagationMode.NESTED} when there is an active outer transaction.
+     *
+     * The manager intentionally does NOT create a new
+     * {@link ActiveTransaction} for the savepoint — hook registrations inside
+     * `fn` fall through {@link currentTransaction} to the outer transaction,
+     * which is the Spring-style semantic: nested events "promote" to the
+     * enclosing transaction and fire when that transaction commits.
+     *
+     * Rollback semantics follow `shouldRollback`: errors that match the
+     * rollback rules cause the adapter to roll back to the savepoint (the
+     * outer transaction is unaffected); errors that do NOT match lead to a
+     * savepoint release (commit-inside-savepoint) and the error is re-raised
+     * to the caller after the release.
+     */
+    private runNestedSavepoint;
+    private currentTransaction;
+    /**
+     * Spring-style decision on whether a thrown error should trigger rollback:
+     *
+     * 1. If `noRollbackFor` is set and matches, commit anyway (precedence).
+     * 2. Else if `rollbackFor` is set, roll back only when the error matches
+     *    an entry — a non-match commits (explicit allow-list semantics).
+     * 3. Else (no rules set), any error triggers rollback — the default
+     *    transactional behaviour.
+     */
+    private shouldRollback;
+    private runHooks;
+}
+//# sourceMappingURL=transaction.manager.d.ts.map