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

package/dist/base/actions.d.ts

@@ -25,6 +25,7 @@ export declare abstract class ActionsBase implements ActionsBaseInterface {
     beginTransaction(id: Id): Promise<TransactionHandle>;
     commitTransaction(handle: TransactionHandle): Promise<void>;
     rollbackTransaction(handle: TransactionHandle): Promise<void>;
+    createIndex(config: VQueryT.CreateIndex): Promise<void>;
     updateOneOrAdd(config: VQueryT.UpdateOneOrAdd): Promise<VQueryT.UpdateOneOrAddResult<DataInternal>>;
     toggleOne(config: VQueryT.ToggleOne): Promise<VQueryT.ToggleOneResult<DataInternal>>;
 }

package/dist/base/actions.js

@@ -19,6 +19,9 @@ export class ActionsBase {
     async rollbackTransaction(handle) {
         throw new Error("Transactions are not supported for ActionsBase");
     }
+    async createIndex(config) {
+        // No-op: adapter does not use indexes internally
+    }
     async updateOneOrAdd(config) {
         const res = await this.updateOne(config);
         if (res)

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

@@ -3,11 +3,13 @@ import { ActionsBase } from "../base/actions.js";
 import { Collection } from "../helpers/collection.js";
 import { ExecutorInterface } from "../helpers/executor.js";
 import { Data } from "../types/data.js";
+import { IndexOpts } from "../types/idx.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
@@ -17,19 +19,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.
      */
@@ -86,17 +87,23 @@ export declare class ValtheraClass implements ValtheraCompatible {
      * Removes a database collection from the database.
      */
     removeCollection(collection: string): Promise<boolean>;
+    /**
+     * Create an index on a collection.
+     */
+    createIndex(collection: string, fields: string[], opts?: IndexOpts): Promise<void>;
     /**
      * @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.
      *
-     * - 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);
     }
     /**
@@ -212,52 +195,68 @@ export class ValtheraClass {
         this._collections.delete(collection);
         return this.execute("removeCollection", collection);
     }
+    /**
+     * Create an index on a collection.
+     */
+    async createIndex(collection, fields, opts) {
+        const index = {
+            collection,
+            fields,
+            opts,
+        };
+        await this.execute("createIndex", {
+            collection,
+            index,
+        });
+    }
     /**
      * @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.
      *
-     * - 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;
-            }
-            catch (err) {
-                try {
-                    await self.adapter.rollbackTransaction(handle);
-                }
-                catch (rollbackErr) {
-                    throw new AggregateError([
-                        err,
-                        rollbackErr,
-                    ], "Transaction failed and rollback failed");
-                }
-                throw err;
+                await tx.rollback();
             }
-            finally {
-                self._activeTx = null;
+            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,17 @@ 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 +35,6 @@ export async function addId(query, actions, defaultGen = true) {
             },
         },
         id_gen: false,
+        ...txOpts,
     });
 }

package/dist/helpers/collection.d.ts

@@ -1,6 +1,7 @@
 import { Arg, Search, Updater } from "../types/arg.js";
 import { UpdateOneOrAdd } from "../types/collection.js";
 import { Data } from "../types/data.js";
+import { IndexOpts } from "../types/idx.js";
 import { DbFindOpts, FindOpts } from "../types/options.js";
 import { VQueryT } from "../types/query.js";
 import { VContext } from "../types/types.js";
@@ -48,4 +49,8 @@ export declare class Collection<D = Data> {
      * 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(search: Search<D>, data?: Arg<D>, context?: VContext): Promise<VQueryT.ToggleOneResult<D>>;
+    /**
+     * Create an index on this collection.
+     */
+    createIndex(fields: string[], opts?: IndexOpts): Promise<void>;
 }

package/dist/helpers/collection.js

@@ -101,4 +101,10 @@ export class Collection {
             context,
         });
     }
+    /**
+     * Create an index on this collection.
+     */
+    createIndex(fields, opts) {
+        return this.db.createIndex(this.collection, fields, opts);
+    }
 }

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

@@ -25,4 +25,5 @@ export interface ActionsBaseInterface {
     beginTransaction(id: Id): Promise<TransactionHandle>;
     commitTransaction(handle: TransactionHandle): Promise<void>;
     rollbackTransaction(handle: TransactionHandle): Promise<void>;
+    createIndex(config: VQueryT.CreateIndex): Promise<void>;
 }

package/dist/types/idx.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Index options - adapter-dependent, should not be relied upon
+ */
+export interface IndexOpts {
+    unique?: boolean;
+    name?: string;
+}
+export interface IndexDefinition {
+    collection: string;
+    fields: string[];
+    opts?: IndexOpts;
+}

package/dist/types/idx.js

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

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

@@ -1,5 +1,6 @@
 import { Arg, Search, Updater } from "./arg.js";
 import { Data } from "./data.js";
+import { IndexDefinition } from "./idx.js";
 import { DbFindOpts, FindOpts } from "./options.js";
 import { TransactionHandle } from "./transaction.js";
 import { VContext } from "./types.js";
@@ -27,11 +28,13 @@ export interface VQuery<T = Data, AllowFn extends boolean = true> {
     updater?: Updater<T, AllowFn>;
     control?: VQuery_Control;
     transaction?: TransactionHandle;
+    index?: IndexDefinition;
 }
 export declare namespace VQueryT {
     type QueryBase<T = Data> = {
         collection: string;
         control?: VQuery_Control;
+        transaction?: TransactionHandle;
     };
     type Add<T = Data> = QueryBase<T> & {
         data: Arg<T>;
@@ -77,4 +80,7 @@ export declare namespace VQueryT {
         data: T;
         type: "added" | "removed";
     }
+    type CreateIndex<T = Data> = QueryBase<T> & {
+        index: IndexDefinition;
+    };
 }

package/dist/types/valthera.d.ts

@@ -1,5 +1,6 @@
 import { Collection } from "../helpers/collection.js";
 import { Data } from "./data.js";
+import { IndexOpts } from "./idx.js";
 import { VQueryT } from "./query.js";
 export interface ValtheraCompatible {
     c<T = Data>(collection: string): Collection<T>;
@@ -16,4 +17,5 @@ export interface ValtheraCompatible {
     removeCollection(collection: string): Promise<boolean>;
     updateOneOrAdd<T = Data>(query: VQueryT.UpdateOneOrAdd<T>): Promise<VQueryT.UpdateOneOrAddResult<T>>;
     toggleOne<T = Data>(query: VQueryT.ToggleOne<T>): Promise<VQueryT.ToggleOneResult<T>>;
+    createIndex(collection: string, fields: string[], opts?: IndexOpts): Promise<void>;
 }

package/dist/version.d.ts

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

package/dist/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wxn0brp/db-core",
-  "version": "0.12.4-alpha.0",
+  "version": "0.12.4-alpha.2",
   "types": "dist/index.d.ts",
   "main": "dist/index.js",
   "author": "wxn0brP",
@@ -13,7 +13,7 @@
   },
   "homepage": "https://github.com/wxn0brP/ValtheraDB",
   "dependencies": {
-    "@wxn0brp/event-emitter": "0.0.6"
+    "@wxn0brp/event-emitter": "0.0.7"
   },
   "devDependencies": {
     "@types/bun": "*",