@navette-js/database 1.0.0-beta.3 → 1.0.0-beta.5

package/lib/index.d.ts

@@ -7,6 +7,8 @@ export type ListQuery = {
     /** Global search: every word must appear in at least one of the searchable columns. */
     search?: string | null;
     searchColumns?: string[];
+    /** `false`: the search term is matched as a whole, instead of word by word. */
+    splitSearchTerms?: boolean;
     /** Per-column search: all conditions must match. */
     columnSearches?: Record<string, string>;
     /** Soft-deleted records: excluded by default, included, or only those. */
@@ -16,10 +18,14 @@ export type ListQuery = {
         direction: SortDirection;
     } | null;
     /** Table grouping: this sort is applied before `sort`. */
+    /** Rows are first ordered by their group: by `column`, or by `modify` (a custom order). */
     groupSort?: {
         column: string;
         direction: SortDirection;
+        modify?: (query: any, direction: SortDirection) => void;
     } | null;
+    /** Only these records (keys), e.g. the rows of the displayed page. */
+    keys?: string[];
     /** Extra server-side conditions (list tab, custom filter); never built from unvalidated browser input. */
     modifiers?: ((query: any) => void)[];
     page: number;
@@ -57,6 +63,8 @@ export interface DataAdapter<T = any> {
     count(): Promise<number>;
     paginate(query: ListQuery): Promise<Page<T>>;
     find(key: string | number): Promise<T | null>;
+    /** Like `find()`, soft-deleted records included (tables that show deleted records). Optional. */
+    findWithTrashed?(key: string | number): Promise<T | null>;
     create(data: Record<string, unknown>): Promise<T>;
     update(key: string | number, data: Record<string, unknown>): Promise<T | null>;
     delete(key: string | number): Promise<boolean>;
@@ -70,7 +78,17 @@ export interface DataAdapter<T = any> {
     deleteMany(keys: (string | number)[]): Promise<number>;
     /** True if another record already has this value (`unique` rule). */
     exists(column: string, value: unknown, exceptKey?: string | number | null): Promise<boolean>;
+    /** Runs `fn` in a database transaction (`panel.databaseTransactions()`); without it, `fn` runs as is. */
+    transaction?<T>(fn: () => Promise<T>): Promise<T>;
 }
+/** The transaction open on this connection in the current async context (`transaction()`), or `null`. */
+export declare function currentTransaction(knex?: Knex): Knex.Transaction | null;
+/**
+ * Runs `fn` in a database transaction: committed when it resolves, rolled back when it throws. Every query made in the
+ * meantime through the connection (`createConnection()`, `sqlite()`: Objection models and `knex(table)` alike) joins it.
+ * Called inside an open transaction, `fn` simply joins it.
+ */
+export declare function transaction<T>(knex: Knex | (() => Promise<T>), fn?: () => Promise<T>): Promise<T>;
 export declare function createConnection(config: Knex.Config): Knex;
 /** SQLite connection (better-sqlite3 driver), for development and demos. */
 export declare function sqlite(filename: string): Knex;
@@ -94,6 +112,10 @@ export declare class ObjectionAdapter<M extends Model> implements DataAdapter<M>
      * (the request's tenant; `null` means no filter). Set by the panel (`panel.tenant()`).
      */
     scopeToTenant(column: string, key: () => string | number | null): this;
+    /** A query of the model, in the open transaction if any. */
+    private query;
+    /** Runs `fn` in a transaction of the model's connection. */
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
     private base;
     private now;
     private get keyColumn();
@@ -137,6 +159,7 @@ export declare class ObjectionAdapter<M extends Model> implements DataAdapter<M>
     private filtered;
     private finishPagination;
     find(key: string | number): Promise<M | null>;
+    findWithTrashed(key: string | number): Promise<M | null>;
     create(data: Record<string, unknown>): Promise<M>;
     update(key: string | number, data: Record<string, unknown>): Promise<M | null>;
     /** With soft deletes, the record is timestamped instead of removed. */

package/lib/index.js

@@ -1,9 +1,48 @@
 // @navette-js/database — data access contract and its Knex + Objection adapter.
+import { AsyncLocalStorage } from 'node:async_hooks';
 import knexFactory from 'knex';
 import { Model } from 'objection';
 export { Model };
+/** Transactions open in the current async context, by connection. */
+const openTransactions = new AsyncLocalStorage();
+const RAW = Symbol('navette.rawKnex');
+const rawOf = (knex) => knex[RAW] ?? knex;
+/** The transaction open on this connection in the current async context (`transaction()`), or `null`. */
+export function currentTransaction(knex = Model.knex()) {
+    return openTransactions.getStore()?.get(rawOf(knex)) ?? null;
+}
+/**
+ * Runs `fn` in a database transaction: committed when it resolves, rolled back when it throws. Every query made in the
+ * meantime through the connection (`createConnection()`, `sqlite()`: Objection models and `knex(table)` alike) joins it.
+ * Called inside an open transaction, `fn` simply joins it.
+ */
+export async function transaction(knex, fn) {
+    if (typeof fn !== 'function') {
+        fn = knex;
+        knex = Model.knex();
+    }
+    const raw = rawOf(knex);
+    const open = openTransactions.getStore();
+    if (open?.has(raw))
+        return fn();
+    return raw.transaction((trx) => openTransactions.run(new Map(open ?? []).set(raw, trx), fn));
+}
+/** The connection, routed to the transaction open in the current async context (`transaction()`), if any. */
+function transactionAware(knex) {
+    const target = () => openTransactions.getStore()?.get(knex) ?? knex;
+    return new Proxy(knex, {
+        apply: (_target, thisArg, args) => Reflect.apply(target(), thisArg, args),
+        get: (_target, property) => {
+            if (property === RAW)
+                return knex;
+            const current = target();
+            const value = Reflect.get(current, property);
+            return typeof value === 'function' && current !== knex && property !== 'constructor' ? value.bind(current) : value;
+        },
+    });
+}
 export function createConnection(config) {
-    const knex = knexFactory(config);
+    const knex = transactionAware(knexFactory(config));
     Model.knex(knex);
     return knex;
 }
@@ -33,8 +72,12 @@ export class ObjectionAdapter {
      * (the request's tenant; `null` means no filter). Set by the panel (`panel.tenant()`).
      */
     scopeToTenant(column, key) { this.tenantScope = { column, key }; return this; }
+    /** A query of the model, in the open transaction if any. */
+    query() { return this.model.query(currentTransaction(this.model.knex()) ?? undefined); }
+    /** Runs `fn` in a transaction of the model's connection. */
+    transaction(fn) { return transaction(this.model.knex(), fn); }
     base(trashed = 'without') {
-        const q = this.model.query();
+        const q = this.query();
         const tenantKey = this.tenantScope?.key() ?? null;
         if (tenantKey !== null)
             q.where(`${this.model.tableName}.${this.tenantScope.column}`, tenantKey);
@@ -127,8 +170,8 @@ export class ObjectionAdapter {
         if (!keys.length)
             return 0;
         if (this.softDeletes)
-            return this.model.query().whereIn(this.keyColumn, keys).whereNull(this.softDeletes).patch({ [this.softDeletes]: this.now() });
-        return this.model.query().delete().whereIn(this.keyColumn, keys);
+            return this.query().whereIn(this.keyColumn, keys).whereNull(this.softDeletes).patch({ [this.softDeletes]: this.now() });
+        return this.query().delete().whereIn(this.keyColumn, keys);
     }
     async paginate(query) {
         return this.finishPagination(this.filtered(query), query);
@@ -136,9 +179,12 @@ export class ObjectionAdapter {
     /** Base query with modifiers, global search and per-column searches applied. */
     filtered(query) {
         const q = this.base(query.trashed ?? 'without');
+        if (query.keys)
+            q.whereIn(`${this.model.tableName}.${this.keyColumn}`, query.keys.map(String).slice(0, 10000));
         for (const modifier of query.modifiers ?? [])
             modifier(q);
-        const words = (query.search ?? '').trim().split(/\s+/).filter(Boolean);
+        const term = (query.search ?? '').trim();
+        const words = query.splitSearchTerms === false ? (term ? [term] : []) : term.split(/\s+/).filter(Boolean);
         const columns = query.searchColumns ?? [];
         if (words.length && columns.length) {
             // Each word must match at least one column, case-insensitively; LIKE wildcards in the input are escaped.
@@ -157,7 +203,9 @@ export class ObjectionAdapter {
     }
     async finishPagination(q, query) {
         const total = await q.clone().resultSize();
-        if (query.groupSort)
+        if (query.groupSort?.modify)
+            query.groupSort.modify(q, query.groupSort.direction);
+        else if (query.groupSort)
             q.orderBy(query.groupSort.column, query.groupSort.direction);
         if (query.sort)
             q.orderBy(query.sort.column, query.sort.direction);
@@ -169,9 +217,10 @@ export class ObjectionAdapter {
         return { records, total, page, perPage, lastPage, from: records.length ? (page - 1) * perPage + 1 : null, to: records.length ? (page - 1) * perPage + records.length : null };
     }
     async find(key) { return (await this.base(this.findsTrashed ? 'with' : 'without').findById(key)) ?? null; }
+    async findWithTrashed(key) { return (await this.base('with').findById(key)) ?? null; }
     async create(data) {
         const tenantKey = this.tenantScope?.key() ?? null;
-        return (await this.model.query().insertAndFetch((tenantKey !== null ? { ...data, [this.tenantScope.column]: tenantKey } : data)));
+        return (await this.query().insertAndFetch((tenantKey !== null ? { ...data, [this.tenantScope.column]: tenantKey } : data)));
     }
     async update(key, data) {
         // Records outside the current tenant cannot be updated, and the tenant column never changes.
@@ -180,24 +229,24 @@ export class ObjectionAdapter {
                 return null;
             data = Object.fromEntries(Object.entries(data).filter(([column]) => column !== this.tenantScope.column));
         }
-        return (await this.model.query().patchAndFetchById(key, data)) ?? null;
+        return (await this.query().patchAndFetchById(key, data)) ?? null;
     }
     /** With soft deletes, the record is timestamped instead of removed. */
     async delete(key) {
         if (this.softDeletes)
-            return (await this.model.query().findById(key).whereNull(this.softDeletes).patch({ [this.softDeletes]: this.now() })) > 0;
-        return (await this.model.query().deleteById(key)) > 0;
+            return (await this.query().findById(key).whereNull(this.softDeletes).patch({ [this.softDeletes]: this.now() })) > 0;
+        return (await this.query().deleteById(key)) > 0;
     }
     supportsSoftDeletes() { return this.softDeletes !== null; }
     isTrashed(record) { return this.softDeletes !== null && record?.[this.softDeletes] != null; }
     async restore(key) {
         if (!this.softDeletes)
             return false;
-        return (await this.model.query().findById(key).whereNotNull(this.softDeletes).patch({ [this.softDeletes]: null })) > 0;
+        return (await this.query().findById(key).whereNotNull(this.softDeletes).patch({ [this.softDeletes]: null })) > 0;
     }
-    async forceDelete(key) { return (await this.model.query().deleteById(key)) > 0; }
+    async forceDelete(key) { return (await this.query().deleteById(key)) > 0; }
     async exists(column, value, exceptKey = null) {
-        const q = this.model.query().where(column, value);
+        const q = this.query().where(column, value);
         if (exceptKey !== null)
             q.whereNot(this.keyColumn, exceptKey);
         return (await q.resultSize()) > 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navette-js/database",
-  "version": "1.0.0-beta.3",
+  "version": "1.0.0-beta.5",
   "description": "Data adapters (Objection/Knex) for Navette panels.",
   "license": "MIT",
   "type": "module",