@decaf-ts/core 0.26.5 → 0.27.0

package/lib/types/persistence/ContextLock.d.cts

@@ -1,18 +1,76 @@
-import { Lock } from "@decaf-ts/transactional-decorators";
 import { type Adapter } from "./Adapter.d.cts";
-export declare class AdapterTransaction<A extends Adapter<any, any, any, any>> {
+import { type Context } from "./Context.d.cts";
+import { Lock } from "@decaf-ts/transactional-decorators";
+/**
+ * @description Counting semaphore used by the default `ContextLock` to gate concurrent transactions
+ * @summary Simple FIFO semaphore: `acquire()` resolves immediately while permits remain, otherwise the
+ * caller is queued and resolved (without touching the permit count) the moment `release()` hands the
+ * permit directly to the next waiter. `SimpleConcurrencyLock.for(adapter, limit)` is the single,
+ * self-contained way to get the one gate shared by every transaction on that adapter - no extra state
+ * or methods live on `Adapter` itself for this.
+ * @class SimpleConcurrencyLock
+ */
+export declare class SimpleConcurrencyLock extends Lock {
+    private static readonly registry;
+    /**
+     * @description Returns the one `SimpleConcurrencyLock` for this adapter, creating it on first use
+     * @summary `limit` only matters the first time it's called for a given adapter - the gate's capacity
+     * is fixed for the adapter's lifetime, the same way the adapter's own client/connection is.
+     */
+    static for(adapter: Adapter<any, any, any, any>, limit: number): SimpleConcurrencyLock;
+    private permits;
+    private readonly waiters;
+    private constructor();
+    acquire(ctx?: Context<any>): Promise<void>;
+    release(ctx?: Context<any>): void;
+}
+/**
+ * @description Per-adapter transaction lock
+ * @summary Default transaction boundary implementation stored on the Context by `@transactional`.
+ * Gated by the `maxConcurrentTransactions` flag (see `AdapterFlags`): `-1` (default) means no limit and
+ * `begin`/`commit`/`rollback` behave as a no-op; `0` disables transactions outright (every call throws);
+ * any positive number gates concurrent transactions through `SimpleConcurrencyLock.for(adapter, limit)`,
+ * the one counting semaphore shared by every transaction on that adapter, queuing callers until a slot
+ * frees up.
+ * Adapters with native transaction support (e.g. a SQL adapter wrapping BEGIN/COMMIT/ROLLBACK) override
+ * `Adapter.transactionLock()` to return a subclass with real `begin`/`commit`/`rollback` behavior - if that
+ * subclass does not call `super.begin()`/`super.commit()`/`super.rollback()`, `maxConcurrentTransactions`
+ * has no effect for it, since concurrency is then governed by the underlying database instead.
+ * `transactionLock()` always returns a *fresh* `ContextLock` per top-level transaction - it's the
+ * per-transaction handle (nesting `depth`, and for native adapters the actual exclusive connection/cursor),
+ * so it cannot be a singleton itself; only the concurrency gate it delegates to is shared.
+ * Nesting (reusing the same instance across nested `@transactional` calls, and deciding when to actually
+ * call `begin`/`commit`/`rollback`) is owned by the `@transactional` proxy via `depth`, not by this class.
+ * @class ContextLock
+ */
+export declare class ContextLock<A extends Adapter<any, any, any, any> = Adapter<any, any, any, any>> {
     protected adapter: A;
+    /**
+     * @description Nesting depth, owned and mutated by the `@transactional` proxy
+     */
+    depth: number;
+    private semaphore?;
     constructor(adapter: A, ...args: any[]);
-    begin(...args: any[]): Promise<void>;
-    commit(...args: any[]): Promise<void>;
-    rollback(...args: any[]): Promise<void>;
-}
-export declare class ContextLock extends Lock {
-    protected adapterTransaction: AdapterTransaction<any>;
-    private acquireCount;
-    protected readonly lock: Lock;
-    constructor(adapterTransaction: AdapterTransaction<any>);
-    acquire(...args: any[]): Promise<void>;
-    release(...args: any[]): Promise<void>;
-    rollback(e: Error, ...args: any[]): Promise<void>;
+    /**
+     * @description Called once, by the outermost `@transactional` call
+     * @summary `context` already exists by the time this is called (the `@transactional` proxy always
+     * builds it before calling `begin`), so this routes it through `Adapter.logCtx()` with `allowCreate`
+     * left at its default `false` - there is nothing to create here, only the existing context (and its
+     * logger) to reuse. Passing `allowCreate: true` would be wrong: it skips the "reuse the context I was
+     * given" branch entirely and tries to build a new one through `Adapter.context()`, whose third
+     * positional parameter is reserved for a model constructor - the context would be misread as "model".
+     * @param {Context<any>} context - The context the transaction is starting under
+     */
+    begin(context: Context<any>): Promise<void>;
+    /**
+     * @description Called once, when the outermost `@transactional` call exits successfully
+     * @param {Context<any>} context - The context the transaction ran under
+     */
+    commit(context: Context<any>): Promise<void>;
+    /**
+     * @description Called once, by whichever call hits the error first. Ends the transaction outright
+     * @param {Error} err - The error that triggered the rollback
+     * @param {Context<any>} context - The context the transaction ran under
+     */
+    rollback(err: Error, context: Context<any>): Promise<void>;
 }

package/lib/types/persistence/ContextLock.d.mts

@@ -1,18 +1,76 @@
-import { Lock } from "@decaf-ts/transactional-decorators";
 import { type Adapter } from "./Adapter.d.mts";
-export declare class AdapterTransaction<A extends Adapter<any, any, any, any>> {
+import { type Context } from "./Context.d.mts";
+import { Lock } from "@decaf-ts/transactional-decorators";
+/**
+ * @description Counting semaphore used by the default `ContextLock` to gate concurrent transactions
+ * @summary Simple FIFO semaphore: `acquire()` resolves immediately while permits remain, otherwise the
+ * caller is queued and resolved (without touching the permit count) the moment `release()` hands the
+ * permit directly to the next waiter. `SimpleConcurrencyLock.for(adapter, limit)` is the single,
+ * self-contained way to get the one gate shared by every transaction on that adapter - no extra state
+ * or methods live on `Adapter` itself for this.
+ * @class SimpleConcurrencyLock
+ */
+export declare class SimpleConcurrencyLock extends Lock {
+    private static readonly registry;
+    /**
+     * @description Returns the one `SimpleConcurrencyLock` for this adapter, creating it on first use
+     * @summary `limit` only matters the first time it's called for a given adapter - the gate's capacity
+     * is fixed for the adapter's lifetime, the same way the adapter's own client/connection is.
+     */
+    static for(adapter: Adapter<any, any, any, any>, limit: number): SimpleConcurrencyLock;
+    private permits;
+    private readonly waiters;
+    private constructor();
+    acquire(ctx?: Context<any>): Promise<void>;
+    release(ctx?: Context<any>): void;
+}
+/**
+ * @description Per-adapter transaction lock
+ * @summary Default transaction boundary implementation stored on the Context by `@transactional`.
+ * Gated by the `maxConcurrentTransactions` flag (see `AdapterFlags`): `-1` (default) means no limit and
+ * `begin`/`commit`/`rollback` behave as a no-op; `0` disables transactions outright (every call throws);
+ * any positive number gates concurrent transactions through `SimpleConcurrencyLock.for(adapter, limit)`,
+ * the one counting semaphore shared by every transaction on that adapter, queuing callers until a slot
+ * frees up.
+ * Adapters with native transaction support (e.g. a SQL adapter wrapping BEGIN/COMMIT/ROLLBACK) override
+ * `Adapter.transactionLock()` to return a subclass with real `begin`/`commit`/`rollback` behavior - if that
+ * subclass does not call `super.begin()`/`super.commit()`/`super.rollback()`, `maxConcurrentTransactions`
+ * has no effect for it, since concurrency is then governed by the underlying database instead.
+ * `transactionLock()` always returns a *fresh* `ContextLock` per top-level transaction - it's the
+ * per-transaction handle (nesting `depth`, and for native adapters the actual exclusive connection/cursor),
+ * so it cannot be a singleton itself; only the concurrency gate it delegates to is shared.
+ * Nesting (reusing the same instance across nested `@transactional` calls, and deciding when to actually
+ * call `begin`/`commit`/`rollback`) is owned by the `@transactional` proxy via `depth`, not by this class.
+ * @class ContextLock
+ */
+export declare class ContextLock<A extends Adapter<any, any, any, any> = Adapter<any, any, any, any>> {
     protected adapter: A;
+    /**
+     * @description Nesting depth, owned and mutated by the `@transactional` proxy
+     */
+    depth: number;
+    private semaphore?;
     constructor(adapter: A, ...args: any[]);
-    begin(...args: any[]): Promise<void>;
-    commit(...args: any[]): Promise<void>;
-    rollback(...args: any[]): Promise<void>;
-}
-export declare class ContextLock extends Lock {
-    protected adapterTransaction: AdapterTransaction<any>;
-    private acquireCount;
-    protected readonly lock: Lock;
-    constructor(adapterTransaction: AdapterTransaction<any>);
-    acquire(...args: any[]): Promise<void>;
-    release(...args: any[]): Promise<void>;
-    rollback(e: Error, ...args: any[]): Promise<void>;
+    /**
+     * @description Called once, by the outermost `@transactional` call
+     * @summary `context` already exists by the time this is called (the `@transactional` proxy always
+     * builds it before calling `begin`), so this routes it through `Adapter.logCtx()` with `allowCreate`
+     * left at its default `false` - there is nothing to create here, only the existing context (and its
+     * logger) to reuse. Passing `allowCreate: true` would be wrong: it skips the "reuse the context I was
+     * given" branch entirely and tries to build a new one through `Adapter.context()`, whose third
+     * positional parameter is reserved for a model constructor - the context would be misread as "model".
+     * @param {Context<any>} context - The context the transaction is starting under
+     */
+    begin(context: Context<any>): Promise<void>;
+    /**
+     * @description Called once, when the outermost `@transactional` call exits successfully
+     * @param {Context<any>} context - The context the transaction ran under
+     */
+    commit(context: Context<any>): Promise<void>;
+    /**
+     * @description Called once, by whichever call hits the error first. Ends the transaction outright
+     * @param {Error} err - The error that triggered the rollback
+     * @param {Context<any>} context - The context the transaction ran under
+     */
+    rollback(err: Error, context: Context<any>): Promise<void>;
 }

package/lib/types/persistence/transactions.d.cts

@@ -1,4 +1,21 @@
-import { Adapter } from "../persistence/Adapter.d.cts";
 import { ContextLock } from "../persistence/ContextLock.d.cts";
-export declare function getAdapterTransaction(obj: any, ...args: any[]): import(".").AdapterTransaction<Adapter<any, any, any, any>>;
-export declare function getContextLock(obj: any, ...args: any[]): ContextLock;
+/**
+ * @description Resolves the transaction lock for a `@transactional`-decorated call
+ * @summary Finds the underlying adapter for the decorated object (Adapter, Repository, or
+ * ModelService) and asks it for a fresh `ContextLock` via `Adapter.transactionLock()`
+ */
+export declare function resolveTransactionLock(obj: any, ...args: any[]): ContextLock;
+/**
+ * @description Method decorator that wraps a method in core's transaction-lock mechanism
+ * @summary `@decaf-ts/transactional-decorators` exports its own `transactional()` factory, and that
+ * factory re-registers its own (base) decorator under the same Decoration key every time it is called
+ * — so importing core does not make core's implementation "stick" if anything also calls the base
+ * package's factory. Consumers that want core's `ContextLock`/per-adapter transaction-lock behavior
+ * MUST import `transactional` from `@decaf-ts/core` (this function), not from
+ * `@decaf-ts/transactional-decorators`. Whichever factory is called last determines the active
+ * implementation for the shared key/flavour going forward.
+ * @param {...any[]} data - Optional metadata available to the transaction-lock implementation
+ * @function transactional
+ * @category Decorators
+ */
+export declare function transactional(...data: any[]): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;

package/lib/types/persistence/transactions.d.mts

@@ -1,4 +1,21 @@
-import { Adapter } from "../persistence/Adapter.d.mts";
 import { ContextLock } from "../persistence/ContextLock.d.mts";
-export declare function getAdapterTransaction(obj: any, ...args: any[]): import(".").AdapterTransaction<Adapter<any, any, any, any>>;
-export declare function getContextLock(obj: any, ...args: any[]): ContextLock;
+/**
+ * @description Resolves the transaction lock for a `@transactional`-decorated call
+ * @summary Finds the underlying adapter for the decorated object (Adapter, Repository, or
+ * ModelService) and asks it for a fresh `ContextLock` via `Adapter.transactionLock()`
+ */
+export declare function resolveTransactionLock(obj: any, ...args: any[]): ContextLock;
+/**
+ * @description Method decorator that wraps a method in core's transaction-lock mechanism
+ * @summary `@decaf-ts/transactional-decorators` exports its own `transactional()` factory, and that
+ * factory re-registers its own (base) decorator under the same Decoration key every time it is called
+ * — so importing core does not make core's implementation "stick" if anything also calls the base
+ * package's factory. Consumers that want core's `ContextLock`/per-adapter transaction-lock behavior
+ * MUST import `transactional` from `@decaf-ts/core` (this function), not from
+ * `@decaf-ts/transactional-decorators`. Whichever factory is called last determines the active
+ * implementation for the shared key/flavour going forward.
+ * @param {...any[]} data - Optional metadata available to the transaction-lock implementation
+ * @function transactional
+ * @category Decorators
+ */
+export declare function transactional(...data: any[]): (target: any, propertyKey?: any, descriptor?: TypedPropertyDescriptor<any>) => any;

package/lib/types/persistence/types.d.cts

@@ -78,6 +78,15 @@ export type AdapterFlags<LOG extends Logger = Logger> = RepositoryFlags<LOG> & C
     paginateByBookmark: boolean;
     dryRun: boolean;
     lock?: ContextLock;
+    /**
+     * @description Maximum number of concurrent transactions the default `ContextLock` allows for this adapter
+     * @summary `-1` (default) means no limit - the default lock behaves as a no-op. `0` disables transactions
+     * entirely (every `@transactional()` call throws). Any positive number gates concurrent transactions through
+     * a counting semaphore, queuing callers until a slot frees up. Adapters with native transaction support
+     * (e.g. a SQL adapter) that fully override `ContextLock.begin()`/`commit()`/`rollback()` are not affected by
+     * this flag - concurrency there is governed by the underlying database instead.
+     */
+    maxConcurrentTransactions: number;
 };
 export type RawResult<R, D extends boolean> = D extends true ? R : {
     data: R;

package/lib/types/persistence/types.d.mts

@@ -78,6 +78,15 @@ export type AdapterFlags<LOG extends Logger = Logger> = RepositoryFlags<LOG> & C
     paginateByBookmark: boolean;
     dryRun: boolean;
     lock?: ContextLock;
+    /**
+     * @description Maximum number of concurrent transactions the default `ContextLock` allows for this adapter
+     * @summary `-1` (default) means no limit - the default lock behaves as a no-op. `0` disables transactions
+     * entirely (every `@transactional()` call throws). Any positive number gates concurrent transactions through
+     * a counting semaphore, queuing callers until a slot frees up. Adapters with native transaction support
+     * (e.g. a SQL adapter) that fully override `ContextLock.begin()`/`commit()`/`rollback()` are not affected by
+     * this flag - concurrency there is governed by the underlying database instead.
+     */
+    maxConcurrentTransactions: number;
 };
 export type RawResult<R, D extends boolean> = D extends true ? R : {
     data: R;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@decaf-ts/core",
-  "version": "0.26.5",
+  "version": "0.27.0",
   "description": "Core persistence module for the decaf framework",
   "type": "module",
   "exports": {