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

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/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

@@ -6,7 +6,9 @@ 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";
+import { Transaction } from "./transaction.js";
 /**
  * Represents a database management class for performing CRUD operations.
  * @class
@@ -16,9 +18,9 @@ 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[];
@@ -27,7 +29,7 @@ export declare class ValtheraClass implements ValtheraCompatible {
     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.
      */
@@ -84,4 +86,19 @@ 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.
+     *
+     * 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.
+     *
+     * - 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>(collections: string[], fn: (tx: Transaction) => Promise<T>): Promise<T>;
 }

package/dist/db/valthera.js

@@ -1,7 +1,10 @@
 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
@@ -34,6 +37,7 @@ export class ValtheraClass {
                 this.adapter.adapterOpts = options.adapterOpts;
             }
         }
+        options.executorAware ??= true;
     }
     async init(...args) {
         if (this.adapter?._inited)
@@ -46,6 +50,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;
@@ -70,8 +75,10 @@ export class ValtheraClass {
             self.adapter._inited = false;
         });
     }
-    async execute(name, query) {
+    async execute(name, query, txHandle) {
         await this.init();
+        if (txHandle && typeof query === "object")
+            query.transaction = txHandle;
         const plugins = this._plugins;
         const self = this;
         let idx = 0;
@@ -81,6 +88,8 @@ export class ValtheraClass {
             next: async () => {
                 if (idx < plugins.length)
                     return plugins[idx++].execute(ctx);
+                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);
             },
         };
@@ -120,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);
     }
     /**
@@ -202,4 +195,54 @@ export class ValtheraClass {
         this._collections.delete(collection);
         return this.execute("removeCollection", collection);
     }
+    /**
+     * @experimental
+     *
+     * 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.
+     *
+     * - 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(collections, fn) {
+        await this.init();
+        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;
+        }
+        catch (err) {
+            try {
+                await tx.rollback();
+            }
+            catch (rollbackErr) {
+                throw new AggregateError([
+                    err,
+                    rollbackErr,
+                ], "Transaction failed and rollback failed");
+            }
+            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/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

@@ -1,10 +1,11 @@
 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;
 }
 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,11 +26,13 @@ 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> = {
         collection: string;
         control?: VQuery_Control;
+        transaction?: TransactionHandle;
     };
     type Add<T = Data> = QueryBase<T> & {
         data: Arg<T>;

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.1";

package/dist/version.js

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

package/package.json

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