@wxn0brp/db-core 0.12.2 → 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/helpers/relation.js

@@ -67,6 +67,8 @@ export async function processRelations(dbs, cfg, data, parentList = null) {
         : [
             data,
         ];
+    if (targets.length === 0)
+        return;
     for (const key in cfg) {
         if (!Object.hasOwn(cfg, key))
             continue;
@@ -158,29 +160,83 @@ export async function processRelations(dbs, cfg, data, parentList = null) {
         else if (type === "nm") {
             if (!through || !through.table || !through.pk || !through.fk)
                 throw new Error(`Relation type "nm" requires a defined "through" in "${key}"`);
-            for (const item of targets) {
-                const pivotDb = dbs[through.db || dbKey];
-                const pivots = await pivotDb.find({
-                    collection: through.table,
-                    search: {
-                        [through.pk]: item[pk],
+            const allSourceIds = targets.map(i => i[pk]);
+            const pivotDb = dbs[through.db || dbKey];
+            const allPivots = await pivotDb.find({
+                collection: through.table,
+                search: {
+                    $in: {
+                        [through.pk]: allSourceIds,
                     },
-                });
-                const ids = pivots.map(p => p[through.fk]);
-                const related = await db.find({
+                },
+            });
+            const pivotMap = new Map();
+            for (const p of allPivots) {
+                const srcId = p[through.pk];
+                const arr = pivotMap.get(srcId) || [];
+                arr.push(p[through.fk]);
+                pivotMap.set(srcId, arr);
+            }
+            const allTargetIds = [
+                ...new Set(allPivots.map(p => p[through.fk])),
+            ];
+            const allRelated = await db.find({
+                collection,
+                search: {
+                    $in: {
+                        [fk]: allTargetIds,
+                    },
+                },
+                findOpts: {
+                    select,
+                },
+            });
+            const targetMap = new Map(allRelated.map(r => [
+                r[fk],
+                r,
+            ]));
+            for (const item of targets) {
+                const targetIds = pivotMap.get(item[pk]) || [];
+                const related = targetIds.map(id => targetMap.get(id)).filter(Boolean);
+                item[as] = related;
+                if (rel.relations && related.length > 0) {
+                    await Promise.all(related.map(row => processRelations(dbs, rel.relations, row)));
+                }
+            }
+        }
+        else if (type === "n1") {
+            const allFkIds = [
+                ...new Set(targets.flatMap(i => i[pk] || [])),
+            ];
+            if (allFkIds.length === 0) {
+                for (const item of targets)
+                    item[as] = null;
+            }
+            else {
+                const [selectSafe, deleteSelect] = autoSelect(rel, fk);
+                const results = await db.find({
                     collection,
                     search: {
                         $in: {
-                            [fk]: ids,
+                            [fk]: allFkIds,
                         },
                     },
                     findOpts: {
-                        select,
+                        select: selectSafe,
                     },
                 });
-                item[as] = related;
-                if (rel.relations) {
-                    await Promise.all(related.map(row => processRelations(dbs, rel.relations, row)));
+                const map = new Map(results.map(row => [
+                    row[fk],
+                    row,
+                ]));
+                for (const item of targets) {
+                    const fks = item[pk] || [];
+                    const result = map.get(fks[0]) || null;
+                    if (result && rel.relations)
+                        await processRelations(dbs, rel.relations, result);
+                    if (deleteSelect && result)
+                        delete result[fk];
+                    item[as] = result;
                 }
             }
         }

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/relation.d.ts

@@ -19,7 +19,7 @@ export declare namespace RelationTypes {
         as?: string;
         select?: string[];
         dbFindOpts?: DbFindOpts;
-        type?: "1" | "11" | "1n" | "nm";
+        type?: "1" | "11" | "1n" | "nm" | "n1";
         relations?: Relation;
         through?: {
             table: string;

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.2";
+export declare const version = "0.12.4-alpha.0";

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wxn0brp/db-core",
-  "version": "0.12.2",
+  "version": "0.12.4-alpha.0",
   "types": "dist/index.d.ts",
   "main": "dist/index.js",
   "author": "wxn0brP",
@@ -17,7 +17,6 @@
   },
   "devDependencies": {
     "@types/bun": "*",
-    "@types/node": "*",
     "fast-check": "^4",
     "tsc-alias": "^1",
     "typescript": "^7"