@sqb/mariadb 6.0.9 → 6.0.11

package/README.md

@@ -62,5 +62,5 @@ SQB is available under [MIT](LICENSE) license.
 [downloads-url]: https://npmjs.org/package/@sqb/mariadb
 [ci-test-image]: https://github.com/panates/sqb/actions/workflows/test.yml/badge.svg
 [ci-test-url]: https://github.com/panates/sqb/actions/workflows/test.yml
-[coveralls-image]: https://coveralls.io/repos/github/sqbjs/sqb/badge.svg?branch=master
+[coveralls-image]: https://coveralls.io/repos/github/panates/sqb/badge.svg?branch=dev
 [coveralls-url]: https://coveralls.io/github/sqbjs/sqb?branch=master

package/constants.d.ts

@@ -0,0 +1,3 @@
+/** This package's own version, kept in step with its `package.json` by `rman version`
+ *  (see `.rmanrc` `version.stamp`) - never edit it by hand. */
+export declare const version = "6.0.11";

package/constants.js

@@ -0,0 +1,3 @@
+/** This package's own version, kept in step with its `package.json` by `rman version`
+ *  (see `.rmanrc` `version.stamp`) - never edit it by hand. */
+export const version = '6.0.11';

package/index.d.ts

@@ -1,4 +1,15 @@
+/**
+ * @sqb/mariadb - `@sqb/connect` database driver for MariaDB, backed by the
+ * `mariadb` npm package.
+ *
+ * Importing this package (even without using any of its exports) registers
+ * {@link MariadbAdapter} with `@sqb/connect`'s `AdapterRegistry` as a side
+ * effect (and, via `@sqb/mariadb-dialect`, `@sqb/builder`'s
+ * `SerializerRegistry`), making `new SqbClient({ dialect: 'mariadb', ... })`
+ * work.
+ */
 import '@sqb/mariadb-dialect';
+export * from './constants.js';
 export * from './mariadb-adapter.js';
 export * from './mariadb-connection.js';
 export * from './mariadb-cursor.js';

package/index.js

@@ -1,6 +1,17 @@
+/**
+ * @sqb/mariadb - `@sqb/connect` database driver for MariaDB, backed by the
+ * `mariadb` npm package.
+ *
+ * Importing this package (even without using any of its exports) registers
+ * {@link MariadbAdapter} with `@sqb/connect`'s `AdapterRegistry` as a side
+ * effect (and, via `@sqb/mariadb-dialect`, `@sqb/builder`'s
+ * `SerializerRegistry`), making `new SqbClient({ dialect: 'mariadb', ... })`
+ * work.
+ */
 import '@sqb/mariadb-dialect';
 import { AdapterRegistry } from '@sqb/connect';
 import { MariadbAdapter } from './mariadb-adapter.js';
+export * from './constants.js';
 export * from './mariadb-adapter.js';
 export * from './mariadb-connection.js';
 export * from './mariadb-cursor.js';

package/mariadb-adapter.d.ts

@@ -1,8 +1,19 @@
 import '@sqb/mariadb-dialect';
 import type { Adapter, ClientConfiguration } from '@sqb/connect';
+/**
+ * `@sqb/connect` {@link Adapter} for MariaDB, wrapping the `mariadb` npm
+ * package. Registered automatically as a side effect of importing this
+ * package - see `index.ts`.
+ */
 export declare class MariadbAdapter implements Adapter {
     driver: string;
     dialect: string;
     features: Adapter.Features;
+    /**
+     * Opens a new `mariadb` driver connection, configured for named
+     * placeholders and JS-`number` results for decimal/bigint/insert-id
+     * values (rather than the driver's default of strings/`BigInt`, for
+     * result-shape parity with `@sqb/mysql`).
+     */
     connect(config: ClientConfiguration): Promise<Adapter.Connection>;
 }

package/mariadb-adapter.js

@@ -1,6 +1,11 @@
 import '@sqb/mariadb-dialect';
 import { createConnection } from 'mariadb';
 import { MariadbConnection } from './mariadb-connection.js';
+/**
+ * `@sqb/connect` {@link Adapter} for MariaDB, wrapping the `mariadb` npm
+ * package. Registered automatically as a side effect of importing this
+ * package - see `index.ts`.
+ */
 export class MariadbAdapter {
     driver = 'mariadb';
     dialect = 'mariadb';
@@ -8,6 +13,12 @@ export class MariadbAdapter {
         cursor: true,
         positionalParams: true,
     };
+    /**
+     * Opens a new `mariadb` driver connection, configured for named
+     * placeholders and JS-`number` results for decimal/bigint/insert-id
+     * values (rather than the driver's default of strings/`BigInt`, for
+     * result-shape parity with `@sqb/mysql`).
+     */
     async connect(config) {
         const cfg = { ...config.driverOptions };
         if (config.host)

package/mariadb-connection.d.ts

@@ -1,18 +1,42 @@
 import type { Adapter, QueryRequest } from '@sqb/connect';
 import type { Connection as MariadbDriverConnection } from 'mariadb';
+/**
+ * `@sqb/connect` {@link Adapter.Connection} wrapping a raw `mariadb` driver
+ * connection: translates `QueryRequest`s into driver calls (including
+ * cursor-mode streaming and `RETURNING`-on-`UPDATE` emulation, since
+ * MariaDB doesn't support that natively) and normalizes results/column
+ * metadata back into SQB's portable shape.
+ */
 export declare class MariadbConnection implements Adapter.Connection {
     private intlcon?;
     private _inTransaction;
     constructor(conn: MariadbDriverConnection);
     get sessionId(): any;
+    /** Forcibly destroys the underlying connection - see the inline comment for why not a graceful `end()`. */
     close(): Promise<void>;
+    /** Rolls back any open transaction, readying the connection to be pooled/reused. */
     reset(): Promise<void>;
+    /** Begins a transaction (`BEGIN`). */
     startTransaction(): Promise<void>;
+    /** Commits the current transaction. */
     commit(): Promise<void>;
+    /** Rolls back the current transaction. */
     rollback(): Promise<void>;
     getInTransaction(): boolean;
+    /** Validates the connection with a trivial `SELECT 1`. */
     test(): Promise<void>;
+    /**
+     * Executes one query: in cursor mode, wraps the driver's row stream in a
+     * {@link MariadbCursor}; for an `UPDATE ... RETURNING`, executes the
+     * update then runs a synthesized follow-up `SELECT` (MariaDB has no
+     * native `RETURNING` on `UPDATE`); otherwise executes directly, reading
+     * result rows/metadata off the driver's response (which carries a result
+     * set for any statement with a `RETURNING` clause or a plain `SELECT`,
+     * and just an affected-row count otherwise).
+     */
     execute(query: QueryRequest): Promise<Adapter.Response>;
+    /** Runs a synthesized `SELECT` and copies its rows/fields onto `out` - used to emulate `RETURNING` on `UPDATE`. */
     private _fillSelectResult;
+    /** Converts the driver's column metadata into SQB's portable {@link Adapter.Field} shape via {@link typeMap}. */
     private _convertFields;
 }

package/mariadb-connection.js

@@ -1,4 +1,5 @@
 import { MariadbCursor } from './mariadb-cursor.js';
+/** Maps the `mariadb` driver's column type names to SQB's portable `{ dataType, jsType }` pair. */
 const typeMap = {
     DECIMAL: { dataType: 'DECIMAL', jsType: 'number' },
     NEWDECIMAL: { dataType: 'DECIMAL', jsType: 'number' },
@@ -32,6 +33,13 @@ const typeMap = {
     GEOMETRY: { dataType: 'GEOMETRY', jsType: 'Buffer' },
     NULL: { dataType: 'UNKNOWN', jsType: 'any' },
 };
+/**
+ * `@sqb/connect` {@link Adapter.Connection} wrapping a raw `mariadb` driver
+ * connection: translates `QueryRequest`s into driver calls (including
+ * cursor-mode streaming and `RETURNING`-on-`UPDATE` emulation, since
+ * MariaDB doesn't support that natively) and normalizes results/column
+ * metadata back into SQB's portable shape.
+ */
 export class MariadbConnection {
     intlcon;
     _inTransaction = false;
@@ -41,6 +49,7 @@ export class MariadbConnection {
     get sessionId() {
         return this.intlcon?.threadId;
     }
+    /** Forcibly destroys the underlying connection - see the inline comment for why not a graceful `end()`. */
     async close() {
         if (!this.intlcon)
             return;
@@ -51,9 +60,11 @@ export class MariadbConnection {
         // and would hang in that case.
         conn.destroy();
     }
+    /** Rolls back any open transaction, readying the connection to be pooled/reused. */
     async reset() {
         return this.rollback();
     }
+    /** Begins a transaction (`BEGIN`). */
     async startTransaction() {
         assertDefined(this.intlcon);
         // MariaDB implicitly commits any already-active transaction when BEGIN
@@ -61,12 +72,14 @@ export class MariadbConnection {
         await this.intlcon.beginTransaction();
         this._inTransaction = true;
     }
+    /** Commits the current transaction. */
     async commit() {
         assertDefined(this.intlcon);
         // COMMIT outside of an active transaction is a no-op in MariaDB.
         await this.intlcon.commit();
         this._inTransaction = false;
     }
+    /** Rolls back the current transaction. */
     async rollback() {
         assertDefined(this.intlcon);
         await this.intlcon.rollback();
@@ -75,10 +88,20 @@ export class MariadbConnection {
     getInTransaction() {
         return this._inTransaction;
     }
+    /** Validates the connection with a trivial `SELECT 1`. */
     async test() {
         assertDefined(this.intlcon);
         await this.intlcon.query('select 1');
     }
+    /**
+     * Executes one query: in cursor mode, wraps the driver's row stream in a
+     * {@link MariadbCursor}; for an `UPDATE ... RETURNING`, executes the
+     * update then runs a synthesized follow-up `SELECT` (MariaDB has no
+     * native `RETURNING` on `UPDATE`); otherwise executes directly, reading
+     * result rows/metadata off the driver's response (which carries a result
+     * set for any statement with a `RETURNING` clause or a plain `SELECT`,
+     * and just an affected-row count otherwise).
+     */
     async execute(query) {
         assertDefined(this.intlcon);
         const intlcon = this.intlcon;
@@ -147,6 +170,7 @@ export class MariadbConnection {
         }
         return out;
     }
+    /** Runs a synthesized `SELECT` and copies its rows/fields onto `out` - used to emulate `RETURNING` on `UPDATE`. */
     async _fillSelectResult(out, sql, params, query) {
         assertDefined(this.intlcon);
         const rowsAsArray = !query.objectRows;
@@ -155,6 +179,7 @@ export class MariadbConnection {
         out.rowType = query.objectRows ? 'object' : 'array';
         out.rows = result;
     }
+    /** Converts the driver's column metadata into SQB's portable {@link Adapter.Field} shape via {@link typeMap}. */
     _convertFields(fields) {
         const result = [];
         for (const f of fields) {
@@ -169,6 +194,7 @@ export class MariadbConnection {
         return result;
     }
 }
+/** Throws if the connection has already been closed. */
 function assertDefined(d) {
     if (d == null)
         throw new Error('DB session is closed');

package/mariadb-cursor.d.ts

@@ -1,5 +1,10 @@
 import type { Readable } from 'node:stream';
 import type { Adapter, RowType } from '@sqb/connect';
+/**
+ * `@sqb/connect` {@link Adapter.Cursor} wrapping the `mariadb` driver's
+ * `queryStream()` result: consumes it via its async iterator, `fetch(n)`
+ * pulling up to `n` rows at a time.
+ */
 export declare class MariadbCursor implements Adapter.Cursor {
     private _iterator?;
     private readonly _rowType;
@@ -9,6 +14,8 @@ export declare class MariadbCursor implements Adapter.Cursor {
     });
     get isClosed(): boolean;
     get rowType(): RowType;
+    /** Stops consuming the stream - see the inline comment for why this uses the stream's own `close()` rather than just dropping the iterator. */
     close(): Promise<void>;
+    /** Pulls up to `nRows` more rows from the stream, or `undefined` once it's exhausted. */
     fetch(nRows: number): Promise<any[] | undefined>;
 }

package/mariadb-cursor.js

@@ -1,3 +1,8 @@
+/**
+ * `@sqb/connect` {@link Adapter.Cursor} wrapping the `mariadb` driver's
+ * `queryStream()` result: consumes it via its async iterator, `fetch(n)`
+ * pulling up to `n` rows at a time.
+ */
 export class MariadbCursor {
     _iterator;
     _rowType;
@@ -13,6 +18,7 @@ export class MariadbCursor {
     get rowType() {
         return this._rowType;
     }
+    /** Stops consuming the stream - see the inline comment for why this uses the stream's own `close()` rather than just dropping the iterator. */
     async close() {
         this._iterator = undefined;
         // mariadb's stream exposes a custom close() that stops pulling further
@@ -20,6 +26,7 @@ export class MariadbCursor {
         // leave it paused mid-backpressure.
         this._stream.close?.();
     }
+    /** Pulls up to `nRows` more rows from the stream, or `undefined` once it's exhausted. */
     async fetch(nRows) {
         if (!this._iterator)
             return undefined;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sqb/mariadb",
   "description": "SQB adapter for the mariadb driver",
-  "version": "6.0.9",
+  "version": "6.0.11",
   "author": "Panates",
   "license": "BSD-3-Clause",
   "homepage": "https://www.sqbjs.org",
@@ -9,9 +9,9 @@
     "tslib": "^2.8.1"
   },
   "peerDependencies": {
-    "@sqb/builder": "^6.0.9",
-    "@sqb/connect": "^6.0.9",
-    "@sqb/mariadb-dialect": "^6.0.9",
+    "@sqb/builder": "^6.0.11",
+    "@sqb/connect": "^6.0.11",
+    "@sqb/mariadb-dialect": "^6.0.11",
     "mariadb": "^3.5.4"
   },
   "type": "module",
@@ -29,7 +29,9 @@
   },
   "contributors": [
     "Eray Hanoglu <e.hanoglu@panates.com>",
-    "Ilker Gurelli <i.gurelli@panates.com>"
+    "Ilker Gurelli <i.gurelli@panates.com>",
+    "Onur Tokel <o.tokel@panates.com>",
+    "Bircan Yuruk <b.yuruk@panates.com>"
   ],
   "repository": {
     "type": "git",
@@ -49,4 +51,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}