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

package/dist/db/transaction.d.ts

@@ -0,0 +1,30 @@
+import { Collection } from "../helpers/collection.js";
+import { Data } from "../types/data.js";
+import { VQueryT } from "../types/query.js";
+import { TransactionHandle } from "../types/transaction.js";
+import { ValtheraClass } from "./valthera.js";
+/**
+ * Transaction context. Operations are executed directly through the parent
+ * database with the transaction handle passed to the executor.
+ */
+export declare class Transaction {
+    readonly handle: TransactionHandle;
+    _parent: ValtheraClass;
+    constructor(handle: TransactionHandle, _parent: ValtheraClass);
+    c<T = Data>(name: string): Collection<T>;
+    add<T = Data>(q: VQueryT.Add<T>): Promise<T>;
+    find<T = Data>(q: VQueryT.Find<T, true>): Promise<T[]>;
+    findOne<T = Data>(q: VQueryT.FindOne<T>): Promise<T>;
+    update<T = Data>(q: VQueryT.Update<T>): Promise<T[]>;
+    updateOne<T = Data>(q: VQueryT.Update<T>): Promise<T>;
+    remove<T = Data>(q: VQueryT.Remove<T>): Promise<T[]>;
+    removeOne<T = Data>(q: VQueryT.Remove<T>): Promise<T>;
+    updateOneOrAdd<T = Data>(q: VQueryT.UpdateOneOrAdd<T>): Promise<VQueryT.UpdateOneOrAddResult<T>>;
+    toggleOne<T = Data>(q: VQueryT.ToggleOne<T>): Promise<VQueryT.ToggleOneResult<T>>;
+    ensureCollection(collection: string): Promise<boolean>;
+    issetCollection(collection: string): Promise<boolean>;
+    getCollections(): Promise<string[]>;
+    removeCollection(collection: string): Promise<boolean>;
+    commit(): Promise<void>;
+    rollback(): Promise<void>;
+}

package/dist/db/transaction.js

@@ -0,0 +1,71 @@
+import { Collection } from "../helpers/collection.js";
+import { applyAddDefaults, applyFindDefaults, applyFindOneDefaults, applyRemoveDefaults, applyToggleOneDefaults, applyUpdateDefaults, applyUpdateOneOrAddDefaults, } from "../helpers/queryDefaults.js";
+/**
+ * Transaction context. Operations are executed directly through the parent
+ * database with the transaction handle passed to the executor.
+ */
+export class Transaction {
+    handle;
+    _parent;
+    constructor(handle, _parent) {
+        this.handle = handle;
+        this._parent = _parent;
+    }
+    c(name) {
+        return new Collection(this, name);
+    }
+    add(q) {
+        applyAddDefaults(q);
+        return this._parent.execute("add", q, this.handle);
+    }
+    find(q) {
+        applyFindDefaults(q);
+        return this._parent.execute("find", q, this.handle);
+    }
+    findOne(q) {
+        applyFindOneDefaults(q);
+        return this._parent.execute("findOne", q, this.handle);
+    }
+    update(q) {
+        applyUpdateDefaults(q);
+        return this._parent.execute("update", q, this.handle);
+    }
+    updateOne(q) {
+        applyUpdateDefaults(q);
+        return this._parent.execute("updateOne", q, this.handle);
+    }
+    remove(q) {
+        applyRemoveDefaults(q);
+        return this._parent.execute("remove", q, this.handle);
+    }
+    removeOne(q) {
+        applyRemoveDefaults(q);
+        return this._parent.execute("removeOne", q, this.handle);
+    }
+    updateOneOrAdd(q) {
+        applyUpdateOneOrAddDefaults(q);
+        return this._parent.execute("updateOneOrAdd", q, this.handle);
+    }
+    toggleOne(q) {
+        applyToggleOneDefaults(q);
+        return this._parent.execute("toggleOne", q, this.handle);
+    }
+    ensureCollection(collection) {
+        return this._parent.adapter.ensureCollection(collection);
+    }
+    issetCollection(collection) {
+        return this._parent.adapter.issetCollection(collection);
+    }
+    getCollections() {
+        return this._parent.adapter.getCollections();
+    }
+    removeCollection(collection) {
+        return this._parent.adapter.removeCollection(collection);
+    }
+    async commit() {
+        await this._parent.adapter.commitTransaction(this.handle);
+    }
+    async rollback() {
+        await this._parent.adapter.rollbackTransaction(this.handle);
+    }
+}

package/dist/db/valthera.d.ts

@@ -8,6 +8,7 @@ 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";
+import { Transaction } from "./transaction.js";
 /**
  * Represents a database management class for performing CRUD operations.
  * @class
@@ -17,19 +18,18 @@ export declare class ValtheraClass implements ValtheraCompatible {
     adapter: ActionsBase;
     executor: ExecutorInterface;
     emitter: VEE<{
-        [K in keyof ValtheraCompatible]: (query: VQuery, result: Awaited<ReturnType<ValtheraCompatible[K]>>) => void;
+        [K in keyof Omit<ValtheraCompatible, "c">]: (query: VQuery, result: Awaited<ReturnType<ValtheraCompatible[K]>>) => void;
     } & {
-        "*": (name: keyof ValtheraCompatible, query: VQuery, result: any) => void;
+        "*": (name: keyof Omit<ValtheraCompatible, "c">, query: VQuery, result: any) => void;
     }>;
     version: string;
     _plugins: ValtheraPlugin[];
     _collections: Map<string, Collection<any>>;
-    _activeTx: TransactionHandle | null;
     plugin(p: ValtheraPlugin): () => void;
     constructor(options: DbOpts);
     init(...args: any[]): Promise<any>;
     close(...args: any[]): Promise<any>;
-    execute<T>(name: keyof ValtheraCompatible, query: VQuery<any> | string): Promise<T>;
+    execute<T>(name: keyof ValtheraCompatible, query: VQuery<any> | string, txHandle?: TransactionHandle): Promise<T>;
     /**
      * Create a new instance of a Collection class.
      */
@@ -91,12 +91,14 @@ export declare class ValtheraClass implements ValtheraCompatible {
      *
      * Executes operations within a transaction. Automatically rolls back on error.
      *
+     * Receives a transaction-scoped object (`tx`) whose operations are executed
+     * within the transaction context.
+     *
      * 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 support depends on the adapter implementation.
+     * - Collections must be declared upfront to ensure proper locking.
+     * - Operations invoked via the original `db` reference are NOT part of the transaction.
      */
-    transaction<T>(fn: (handle: TransactionHandle) => Promise<T>): Promise<T>;
+    transaction<T>(collections: string[], fn: (tx: Transaction) => Promise<T>): Promise<T>;
 }

package/dist/db/valthera.js

@@ -2,7 +2,9 @@ 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 { applyAddDefaults, applyFindDefaults, applyFindOneDefaults, applyRemoveDefaults, applyToggleOneDefaults, applyUpdateDefaults, applyUpdateOneOrAddDefaults, } from "../helpers/queryDefaults.js";
 import { version } from "../version.js";
+import { Transaction } from "./transaction.js";
 /**
  * Represents a database management class for performing CRUD operations.
  * @class
@@ -15,7 +17,6 @@ export class ValtheraClass {
     version = version;
     _plugins = [];
     _collections = new Map();
-    _activeTx = null;
     plugin(p) {
         p.init?.(this);
         this._plugins.push(p);
@@ -74,12 +75,10 @@ export class ValtheraClass {
             self.adapter._inited = false;
         });
     }
-    async execute(name, query) {
+    async execute(name, query, txHandle) {
         await this.init();
-        const isTransaction = this._activeTx && typeof query !== "string";
-        if (isTransaction) {
-            query.transaction = this._activeTx;
-        }
+        if (txHandle && typeof query === "object")
+            query.transaction = txHandle;
         const plugins = this._plugins;
         const self = this;
         let idx = 0;
@@ -89,8 +88,8 @@ export class ValtheraClass {
             next: async () => {
                 if (idx < plugins.length)
                     return plugins[idx++].execute(ctx);
-                if (isTransaction)
-                    return self.adapter[name](query);
+                if (txHandle)
+                    return self.adapter[ctx.op](query, txHandle);
                 return self.executor.addOp(self.adapter[ctx.op].bind(self.adapter), ctx.query, typeof ctx.query === "string" ? ctx.query : ctx.query.collection);
             },
         };
@@ -130,79 +129,63 @@ export class ValtheraClass {
      * Add data to a database.
      */
     add(query) {
-        query.control ||= {};
-        query.id_gen ??= true;
+        applyAddDefaults(query);
         return this.execute("add", query);
     }
     /**
      * Find data in a database.
      */
     find(query) {
-        query.search ||= {};
-        query.dbFindOpts ||= {};
-        query.findOpts ||= {};
-        query.context ||= {};
-        query.control ||= {};
+        applyFindDefaults(query);
         return this.execute("find", query);
     }
     /**
      * Find one data entry in a database.
      */
     findOne(query) {
-        query.findOpts ||= {};
-        query.context ||= {};
-        query.control ||= {};
+        applyFindOneDefaults(query);
         return this.execute("findOne", query);
     }
     /**
      * Update data in a database.
      */
     update(query) {
-        query.context ||= {};
-        query.control ||= {};
+        applyUpdateDefaults(query);
         return this.execute("update", query);
     }
     /**
      * Update one data entry in a database.
      */
     updateOne(query) {
-        query.context ||= {};
-        query.control ||= {};
+        applyUpdateDefaults(query);
         return this.execute("updateOne", query);
     }
     /**
      * Remove data from a database.
      */
     remove(query) {
-        query.context ||= {};
-        query.control ||= {};
+        applyRemoveDefaults(query);
         return this.execute("remove", query);
     }
     /**
      * Remove one data entry from a database.
      */
     removeOne(query) {
-        query.context ||= {};
-        query.control ||= {};
+        applyRemoveDefaults(query);
         return this.execute("removeOne", query);
     }
     /**
      * Asynchronously updates one entry in a database or adds a new one if it doesn't exist.
      */
     updateOneOrAdd(query) {
-        query.context ||= {};
-        query.add_arg ||= {};
-        query.control ||= {};
-        query.id_gen ??= true;
+        applyUpdateOneOrAddDefaults(query);
         return this.execute("updateOneOrAdd", query);
     }
     /**
      * Asynchronously removes one entry in a database or adds a new one if it doesn't exist. Usage e.g. for toggling a flag.
      */
     toggleOne(query) {
-        query.data ||= {};
-        query.context ||= {};
-        query.control ||= {};
+        applyToggleOneDefaults(query);
         return this.execute("toggleOne", query);
     }
     /**
@@ -217,47 +200,49 @@ export class ValtheraClass {
      *
      * Executes operations within a transaction. Automatically rolls back on error.
      *
+     * Receives a transaction-scoped object (`tx`) whose operations are executed
+     * within the transaction context.
+     *
      * 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 support depends on the adapter implementation.
+     * - Collections must be declared upfront to ensure proper locking.
+     * - Operations invoked via the original `db` reference are NOT part of the transaction.
      */
-    async transaction(fn) {
+    async transaction(collections, 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.");
+        const releases = [];
+        const promises = collections.map(collection => {
+            let started;
+            const startedPromise = new Promise(r => (started = r));
+            this.executor.addOp(async () => {
+                started();
+                await new Promise(resolve => releases.push(resolve));
+            }, undefined, collection);
+            return startedPromise;
+        });
+        await Promise.all(promises);
+        const handle = await this.adapter.beginTransaction(genId());
+        const tx = new Transaction(handle, this);
+        try {
+            const result = await fn(tx);
+            await tx.commit();
+            return result;
         }
-        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;
+        catch (err) {
             try {
-                const result = await fn(handle);
-                await self.adapter.commitTransaction(handle);
-                return result;
+                await tx.rollback();
             }
-            catch (err) {
-                try {
-                    await self.adapter.rollbackTransaction(handle);
-                }
-                catch (rollbackErr) {
-                    throw new AggregateError([
-                        err,
-                        rollbackErr,
-                    ], "Transaction failed and rollback failed");
-                }
-                throw err;
+            catch (rollbackErr) {
+                throw new AggregateError([
+                    err,
+                    rollbackErr,
+                ], "Transaction failed and rollback failed");
             }
-            finally {
-                self._activeTx = null;
-            }
-        });
+            throw err;
+        }
+        finally {
+            releases.forEach(release => release());
+        }
     }
 }

package/dist/helpers/addId.js

@@ -11,11 +11,13 @@ export async function addId(query, actions, defaultGen = true) {
         data[idKey] = genId();
         return;
     }
+    const txOpts = query.transaction ? { transaction: query.transaction } : {};
     const find = (await actions.findOne({
         collection: "__vdb_id",
         search: {
             c: collection,
         },
+        ...txOpts,
     }));
     data[idKey] = find?.i ? find.i + 1 : 1;
     await actions.updateOneOrAdd({
@@ -29,5 +31,6 @@ export async function addId(query, actions, defaultGen = true) {
             },
         },
         id_gen: false,
+        ...txOpts,
     });
 }

package/dist/helpers/queryDefaults.d.ts

@@ -0,0 +1,8 @@
+import { VQueryT } from "../types/query.js";
+export declare function applyAddDefaults<T>(q: VQueryT.Add<T>): void;
+export declare function applyFindDefaults<T>(q: VQueryT.Find<T>): void;
+export declare function applyFindOneDefaults<T>(q: VQueryT.FindOne<T>): void;
+export declare function applyUpdateDefaults<T>(q: VQueryT.Update<T>): void;
+export declare function applyRemoveDefaults<T>(q: VQueryT.Remove<T>): void;
+export declare function applyUpdateOneOrAddDefaults<T>(q: VQueryT.UpdateOneOrAdd<T>): void;
+export declare function applyToggleOneDefaults<T>(q: VQueryT.ToggleOne<T>): void;

package/dist/helpers/queryDefaults.js

@@ -0,0 +1,35 @@
+export function applyAddDefaults(q) {
+    q.control ||= {};
+    q.id_gen ??= true;
+}
+export function applyFindDefaults(q) {
+    q.search ||= {};
+    q.dbFindOpts ||= {};
+    q.findOpts ||= {};
+    q.context ||= {};
+    q.control ||= {};
+}
+export function applyFindOneDefaults(q) {
+    q.findOpts ||= {};
+    q.context ||= {};
+    q.control ||= {};
+}
+export function applyUpdateDefaults(q) {
+    q.context ||= {};
+    q.control ||= {};
+}
+export function applyRemoveDefaults(q) {
+    q.context ||= {};
+    q.control ||= {};
+}
+export function applyUpdateOneOrAddDefaults(q) {
+    q.context ||= {};
+    q.add_arg ||= {};
+    q.control ||= {};
+    q.id_gen ??= true;
+}
+export function applyToggleOneDefaults(q) {
+    q.data ||= {};
+    q.context ||= {};
+    q.control ||= {};
+}

package/dist/types/options.d.ts

@@ -1,10 +1,10 @@
 import { ActionsBase } from "../base/actions.js";
-import { Executor } from "../helpers/executor.js";
+import { ExecutorInterface } from "../helpers/executor.js";
 import { KeysMatching } from "./utils.js";
 export type AdapterValue = ActionsBase | (() => Promise<ActionsBase>);
 export interface DbOpts {
     adapter: AdapterValue;
-    executor?: Executor;
+    executor?: ExecutorInterface;
     executorAware?: boolean;
     adapterOpts?: AdapterOpts;
 }

package/dist/types/query.d.ts

@@ -32,6 +32,7 @@ export declare namespace VQueryT {
     type QueryBase<T = Data> = {
         collection: string;
         control?: VQuery_Control;
+        transaction?: TransactionHandle;
     };
     type Add<T = Data> = QueryBase<T> & {
         data: Arg<T>;

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

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