@opra/sqb 1.28.4 → 1.29.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Panates
+Copyright (c) 2020-present Panates®
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,19 +1,74 @@
+<div align="center">
+
+<a href="https://oprajs.com">
+  <img src="https://oprajs.com/img/opra-header-block.webp" width="880" alt="OPRA — Open Platform for Rich APIs" />
+</a>
+
 # @opra/sqb
 
+SQL data service adapter for the OPRA framework, powered by SQB
+
 [![NPM Version][npm-image]][npm-url]
 [![NPM Downloads][downloads-image]][downloads-url]
 [![CI Tests][ci-test-image]][ci-test-url]
 [![Test Coverage][coveralls-image]][coveralls-url]
 
+[🌐 Documentation](https://oprajs.com) · [🚀 Getting Started](https://oprajs.com/docs/introduction) · [📦 Packages](https://github.com/panates/opra#packages) · [💬 Issues](https://github.com/panates/opra/issues)
+
+</div>
+
+---
+
+SQL data service adapter for the [OPRA](https://oprajs.com) framework, powered by [SQB](https://github.com/panates/sqb). Connect your relational database to OPRA's operation model with full transaction support.
+
+## Features
+
+- **`SqbServiceBase`** — Base service managing SqbClient or SqbConnection with transaction support
+- **`SqbCollectionService`** — Table-level CRUD service with automatic query generation
+- **`SqbEntityService`** — Row-level service for single entity operations
+- **`SQBAdapter`** — Utility namespace: `prepareFilter()`, `parseRequest()`
+- Automatic translation of OPRA filter DSL to SQL WHERE clauses
+- `withTransaction()` helper for multi-step atomic operations
+- Compatible with PostgreSQL, MySQL, SQLite, and other SQB-supported databases
+
+## Installation
 
-## Support
-You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/opra/issues) page.
+```bash
+npm install @opra/sqb
+```
+
+## Usage
+
+```typescript
+import { SqbCollectionService } from '@opra/sqb';
+import { SqbClient } from '@sqb/connect';
+
+@HttpController({ path: 'orders' })
+export class OrdersController extends SqbCollectionService<Order> {
+  constructor(client: SqbClient) {
+    super(Order, client, 'orders');
+  }
+
+  @HttpOperation.Entity.FindMany({ type: Order })
+  findMany() {
+    return super.findMany();
+  }
+
+  @HttpOperation.Entity.Create({ type: Order })
+  async create(dto: CreateOrderDto) {
+    return this.withTransaction(conn =>
+      super.create(dto, { connection: conn }),
+    );
+  }
+}
+```
 
 ## Node Compatibility
-- node >= 20.x
 
+- node >= 20.x
 
 ## License
+
 Available under [MIT](LICENSE) license.
 
 [npm-image]: https://img.shields.io/npm/v/@opra/sqb

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@opra/sqb",
-  "version": "1.28.4",
+  "version": "1.29.0",
   "description": "Opra SQB adapter package",
   "author": "Panates",
   "license": "MIT",
+  "homepage": "https://www.oprajs.com",
   "dependencies": {
     "reflect-metadata": "^0.2.2",
     "tslib": "^2.8.1",
-    "valgen": "^6.2.0"
+    "valgen": "^6.2.2"
   },
   "peerDependencies": {
-    "@opra/core": "^1.28.4",
-    "@opra/http": "^1.28.4",
+    "@opra/core": "^1.29.0",
+    "@opra/http": "^1.29.0",
     "@sqb/builder": ">=5.0.1 <6",
     "@sqb/connect": ">=5.0.1 <6"
   },

package/sqb-service-base.d.ts

@@ -41,5 +41,5 @@ export declare class SqbServiceBase extends ServiceBase {
      *
      * @throws If no database connection is configured.
      */
-    getConnection(): SqbConnection | SqbClient | Promise<SqbConnection | SqbClient>;
+    getConnection(): Promise<SqbConnection | SqbClient>;
 }

package/sqb-service-base.js

@@ -1,6 +1,6 @@
 import { ServiceBase } from '@opra/core';
 import { SqbClient, SqbConnection } from '@sqb/connect';
-const transactionKey = Symbol.for('transaction');
+const dbSessionKey = Symbol.for('db-session');
 /**
  * Base class for services using SQB (SQL Builder) for database operations.
  */
@@ -28,7 +28,7 @@ export class SqbServiceBase extends ServiceBase {
     async withTransaction(callback) {
         const ctx = this.context;
         let closeSessionOnFinish = false;
-        let connection = ctx[transactionKey];
+        let connection = ctx[dbSessionKey] || ctx.bundle?.[dbSessionKey];
         if (!connection) {
             /* Determine the SqbClient or SqbConnection instance */
             const db = await this.getConnection();
@@ -41,7 +41,7 @@ export class SqbServiceBase extends ServiceBase {
                 closeSessionOnFinish = true;
             }
             /* Store transaction connection in current context */
-            ctx[transactionKey] = connection;
+            ctx[dbSessionKey] = connection;
         }
         const oldInTransaction = connection.inTransaction;
         connection.retain();
@@ -59,7 +59,7 @@ export class SqbServiceBase extends ServiceBase {
             throw e;
         }
         finally {
-            delete ctx[transactionKey];
+            delete ctx[dbSessionKey];
             /* Release connection */
             if (closeSessionOnFinish) {
                 await connection.close();
@@ -73,14 +73,40 @@ export class SqbServiceBase extends ServiceBase {
      *
      * @throws If no database connection is configured.
      */
-    getConnection() {
+    async getConnection() {
         const ctx = this.context;
-        let db = ctx[transactionKey];
+        let db = ctx[dbSessionKey] || ctx.bundle?.[dbSessionKey];
         if (db)
             return db;
         db = typeof this.db === 'function' ? this.db(this) : this.db;
-        if (db)
-            return db;
-        throw new Error(`Database not set!`);
+        if (!db)
+            throw new Error(`Database not set!`);
+        if (ctx.bundle?.transaction) {
+            const connection = db instanceof SqbConnection
+                ? db
+                : await db.acquire({ autoCommit: false });
+            /* Start transaction */
+            if (!connection.inTransaction) {
+                await connection.startTransaction();
+            }
+            ctx.bundle[dbSessionKey] = connection;
+            /* Commit or Rollback transaction after executed */
+            ctx.bundle.on('after-execute', async () => {
+                delete ctx.bundle[dbSessionKey];
+                try {
+                    if (connection.inTransaction) {
+                        if (ctx.bundle.success)
+                            await connection.commit();
+                        else
+                            await connection.rollback();
+                    }
+                }
+                finally {
+                    await connection.close();
+                }
+            });
+            return connection;
+        }
+        return db;
     }
 }