@wxn0brp/db-core 0.12.3 → 0.12.4-alpha.0

package/dist/base/actions.d.ts

@@ -1,7 +1,9 @@
 import { ActionsBaseInterface } from "../types/action.js";
 import { DataInternal } from "../types/data.js";
+import { Id } from "../types/Id.js";
 import { AdapterOpts } from "../types/options.js";
 import { VQueryT } from "../types/query.js";
+import { TransactionHandle } from "../types/transaction.js";
 export declare abstract class ActionsBase implements ActionsBaseInterface {
     _inited: boolean;
     adapterOpts: AdapterOpts;
@@ -20,6 +22,9 @@ export declare abstract class ActionsBase implements ActionsBaseInterface {
     abstract updateOne(config: VQueryT.Update): Promise<DataInternal | null>;
     abstract remove(config: VQueryT.Remove): Promise<DataInternal[]>;
     abstract removeOne(config: VQueryT.Remove): Promise<DataInternal | null>;
+    beginTransaction(id: Id): Promise<TransactionHandle>;
+    commitTransaction(handle: TransactionHandle): Promise<void>;
+    rollbackTransaction(handle: TransactionHandle): Promise<void>;
     updateOneOrAdd(config: VQueryT.UpdateOneOrAdd): Promise<VQueryT.UpdateOneOrAddResult<DataInternal>>;
     toggleOne(config: VQueryT.ToggleOne): Promise<VQueryT.ToggleOneResult<DataInternal>>;
 }

package/dist/base/actions.js

@@ -10,6 +10,15 @@ export class ActionsBase {
     version = "ActionsBase-core-" + version;
     async init(...args) { }
     async close(...args) { }
+    async beginTransaction(id) {
+        throw new Error("Transactions are not supported for ActionsBase");
+    }
+    async commitTransaction(handle) {
+        throw new Error("Transactions are not supported for ActionsBase");
+    }
+    async rollbackTransaction(handle) {
+        throw new Error("Transactions are not supported for ActionsBase");
+    }
     async updateOneOrAdd(config) {
         const res = await this.updateOne(config);
         if (res)

package/dist/db/multiStorage.d.ts

@@ -1,5 +1,6 @@
 import { ActionsBase } from "../base/actions.js";
 import { VQueryT } from "../types/query.js";
+import { TransactionHandle } from "../types/transaction.js";
 export declare class MultiBackend extends ActionsBase {
     backends: ActionsBase[];
     primaryBackend: ActionsBase;
@@ -17,4 +18,7 @@ export declare class MultiBackend extends ActionsBase {
     issetCollection(collection: string): Promise<boolean>;
     removeCollection(collection: string): Promise<boolean>;
     getCollections(): Promise<string[]>;
+    beginTransaction(): Promise<TransactionHandle>;
+    commitTransaction(): Promise<void>;
+    rollbackTransaction(): Promise<void>;
 }

package/dist/db/multiStorage.js

@@ -100,4 +100,13 @@ export class MultiBackend extends ActionsBase {
         });
         return Array.from(uniqueCollections);
     }
+    async beginTransaction() {
+        throw new Error("Transactions are not supported for MultiBackend");
+    }
+    async commitTransaction() {
+        throw new Error("Transactions are not supported for MultiBackend");
+    }
+    async rollbackTransaction() {
+        throw new Error("Transactions are not supported for MultiBackend");
+    }
 }

package/dist/db/routedStorage.d.ts

@@ -1,5 +1,6 @@
 import { ActionsBase } from "../base/actions.js";
 import { VQueryT, VQuery } from "../types/query.js";
+import { TransactionHandle } from "../types/transaction.js";
 export type MatchRule = string | RegExp | ((config: VQuery) => boolean);
 export interface RouteEntry {
     match: MatchRule;
@@ -25,4 +26,7 @@ export declare class RoutedStorage extends ActionsBase {
     issetCollection(collection: string): Promise<boolean>;
     removeCollection(collection: string): Promise<boolean>;
     getCollections(): Promise<string[]>;
+    beginTransaction(): Promise<TransactionHandle>;
+    commitTransaction(): Promise<void>;
+    rollbackTransaction(): Promise<void>;
 }

package/dist/db/routedStorage.js

@@ -96,4 +96,13 @@ export class RoutedStorage extends ActionsBase {
         const merged = new Set(all.flat());
         return Array.from(merged);
     }
+    async beginTransaction() {
+        throw new Error("Transactions are not supported for RoutedStorage");
+    }
+    async commitTransaction() {
+        throw new Error("Transactions are not supported for RoutedStorage");
+    }
+    async rollbackTransaction() {
+        throw new Error("Transactions are not supported for RoutedStorage");
+    }
 }

package/dist/db/valthera.d.ts

@@ -6,6 +6,7 @@ import { Data } from "../types/data.js";
 import { DbOpts } from "../types/options.js";
 import { ValtheraPlugin } from "../types/plugin.js";
 import { VQuery, VQueryT } from "../types/query.js";
+import { TransactionHandle } from "../types/transaction.js";
 import { ValtheraCompatible } from "../types/valthera.js";
 /**
  * Represents a database management class for performing CRUD operations.
@@ -23,6 +24,7 @@ export declare class ValtheraClass implements ValtheraCompatible {
     version: string;
     _plugins: ValtheraPlugin[];
     _collections: Map<string, Collection<any>>;
+    _activeTx: TransactionHandle | null;
     plugin(p: ValtheraPlugin): () => void;
     constructor(options: DbOpts);
     init(...args: any[]): Promise<any>;
@@ -84,4 +86,17 @@ export declare class ValtheraClass implements ValtheraCompatible {
      * Removes a database collection from the database.
      */
     removeCollection(collection: string): Promise<boolean>;
+    /**
+     * @experimental
+     *
+     * Executes operations within a transaction. Automatically rolls back on error.
+     *
+     * This feature is highly experimental and may change or be removed at any time.
+     *
+     * - Requires `executorAware: false` in ValtheraClass options.
+     * - Transaction support depends on the executor implementation.
+     * - Nested transactions are not supported.
+     * - Transactions lock the whole database for the duration of the transaction.
+     */
+    transaction<T>(fn: (handle: TransactionHandle) => Promise<T>): Promise<T>;
 }

package/dist/db/valthera.js

@@ -1,6 +1,7 @@
 import { VEE } from "@wxn0brp/event-emitter";
 import { Collection } from "../helpers/collection.js";
 import { SmartExecutor } from "../helpers/executor.js";
+import { genId } from "../helpers/gen.js";
 import { version } from "../version.js";
 /**
  * Represents a database management class for performing CRUD operations.
@@ -14,6 +15,7 @@ export class ValtheraClass {
     version = version;
     _plugins = [];
     _collections = new Map();
+    _activeTx = null;
     plugin(p) {
         p.init?.(this);
         this._plugins.push(p);
@@ -34,6 +36,7 @@ export class ValtheraClass {
                 this.adapter.adapterOpts = options.adapterOpts;
             }
         }
+        options.executorAware ??= true;
     }
     async init(...args) {
         if (this.adapter?._inited)
@@ -46,6 +49,7 @@ export class ValtheraClass {
                 self.adapter = await self.options.adapter();
             // if the executor is not set, and the action wants a smart executor
             if (!self.options.executor &&
+                self.options.executorAware &&
                 self.adapter.smartExecutor &&
                 self.executor instanceof SmartExecutor)
                 self.executor.aware = true;
@@ -72,6 +76,10 @@ export class ValtheraClass {
     }
     async execute(name, query) {
         await this.init();
+        const isTransaction = this._activeTx && typeof query !== "string";
+        if (isTransaction) {
+            query.transaction = this._activeTx;
+        }
         const plugins = this._plugins;
         const self = this;
         let idx = 0;
@@ -81,6 +89,8 @@ export class ValtheraClass {
             next: async () => {
                 if (idx < plugins.length)
                     return plugins[idx++].execute(ctx);
+                if (isTransaction)
+                    return self.adapter[name](query);
                 return self.executor.addOp(self.adapter[ctx.op].bind(self.adapter), ctx.query, typeof ctx.query === "string" ? ctx.query : ctx.query.collection);
             },
         };
@@ -202,4 +212,52 @@ export class ValtheraClass {
         this._collections.delete(collection);
         return this.execute("removeCollection", collection);
     }
+    /**
+     * @experimental
+     *
+     * Executes operations within a transaction. Automatically rolls back on error.
+     *
+     * This feature is highly experimental and may change or be removed at any time.
+     *
+     * - Requires `executorAware: false` in ValtheraClass options.
+     * - Transaction support depends on the executor implementation.
+     * - Nested transactions are not supported.
+     * - Transactions lock the whole database for the duration of the transaction.
+     */
+    async transaction(fn) {
+        await this.init();
+        if ("aware" in this.executor && this.executor.aware) {
+            throw new Error("Transactions are not supported when using a smart executor. " +
+                "Please use options.executorAware = false when creating the Valthera instance.");
+        }
+        if (this._activeTx)
+            throw new Error("Nested transactions are not supported");
+        const self = this;
+        return this.executor.addOp(async () => {
+            if (self._activeTx)
+                throw new Error("Nested transactions are not supported");
+            const handle = await self.adapter.beginTransaction(genId());
+            self._activeTx = handle;
+            try {
+                const result = await fn(handle);
+                await self.adapter.commitTransaction(handle);
+                return result;
+            }
+            catch (err) {
+                try {
+                    await self.adapter.rollbackTransaction(handle);
+                }
+                catch (rollbackErr) {
+                    throw new AggregateError([
+                        err,
+                        rollbackErr,
+                    ], "Transaction failed and rollback failed");
+                }
+                throw err;
+            }
+            finally {
+                self._activeTx = null;
+            }
+        });
+    }
 }

package/dist/types/action.d.ts

@@ -1,6 +1,8 @@
 import { DataInternal } from "./data.js";
+import { Id } from "./Id.js";
 import { AdapterOpts } from "./options.js";
 import { VQueryT } from "./query.js";
+import { TransactionHandle } from "./transaction.js";
 export interface ActionsBaseInterface {
     _inited: boolean;
     adapterOpts: AdapterOpts;
@@ -20,4 +22,7 @@ export interface ActionsBaseInterface {
     removeOne(query: VQueryT.Remove): Promise<DataInternal | null>;
     updateOneOrAdd(query: VQueryT.UpdateOneOrAdd): Promise<VQueryT.UpdateOneOrAddResult<DataInternal>>;
     toggleOne(query: VQueryT.ToggleOne): Promise<VQueryT.ToggleOneResult<DataInternal>>;
+    beginTransaction(id: Id): Promise<TransactionHandle>;
+    commitTransaction(handle: TransactionHandle): Promise<void>;
+    rollbackTransaction(handle: TransactionHandle): Promise<void>;
 }

package/dist/types/options.d.ts

@@ -5,6 +5,7 @@ export type AdapterValue = ActionsBase | (() => Promise<ActionsBase>);
 export interface DbOpts {
     adapter: AdapterValue;
     executor?: Executor;
+    executorAware?: boolean;
     adapterOpts?: AdapterOpts;
 }
 export interface AdapterOpts {

package/dist/types/query.d.ts

@@ -1,6 +1,7 @@
 import { Arg, Search, Updater } from "./arg.js";
 import { Data } from "./data.js";
 import { DbFindOpts, FindOpts } from "./options.js";
+import { TransactionHandle } from "./transaction.js";
 import { VContext } from "./types.js";
 /**
  * To extend via adapters
@@ -25,6 +26,7 @@ export interface VQuery<T = Data, AllowFn extends boolean = true> {
     add_arg?: Arg<T>;
     updater?: Updater<T, AllowFn>;
     control?: VQuery_Control;
+    transaction?: TransactionHandle;
 }
 export declare namespace VQueryT {
     type QueryBase<T = Data> = {

package/dist/types/transaction.d.ts

@@ -0,0 +1,4 @@
+export interface TransactionHandle {
+    id: string;
+    _adapterData?: unknown;
+}

package/dist/types/transaction.js

@@ -0,0 +1 @@
+export {};

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.12.3";
+export declare const version = "0.12.4-alpha.0";

package/dist/version.js

@@ -1 +1 @@
-export const version = "0.12.3";
+export const version = "0.12.4-alpha.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wxn0brp/db-core",
-  "version": "0.12.3",
+  "version": "0.12.4-alpha.0",
   "types": "dist/index.d.ts",
   "main": "dist/index.js",
   "author": "wxn0brP",