@samet-it/be-db-common 1.0.11

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2025 Samet Global
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Web: https://sametglobal.com
+Responsible: Mustafa Yelmer (mustafay@samet.com.tr)

package/README.md

@@ -0,0 +1,74 @@
+# Samet IT : DB Common
+`ts` `component` `backend`
+```
+       ____                                                
+  ____/ / /_     _________  ____ ___  ____ ___  ____  ____ 
+ / __  / __ \   / ___/ __ \/ __ `__ \/ __ `__ \/ __ \/ __ \
+/ /_/ / /_/ /  / /__/ /_/ / / / / / / / / / / / /_/ / / / /
+\__,_/_.___/   \___/\____/_/ /_/ /_/_/ /_/ /_/\____/_/ /_/ 
+```
+<!-- https://patorjk.com/software/taag/#p=display&f=Slant&t=db+common&x=none&v=4&h=3&w=80&we=false -->
+- `EN`: It's db component
+- `TR`: Nodejs projeleri veritabanı temel bileşeni
+
+## Prerequisite
+- [Help](https://github.com/samet-digital/help)
+- [1 - Install Git](https://github.com/samet-digital/help/blob/main//install-git.MD)
+- [2 - Build Up a Git Connection](https://github.com/samet-digital/help/blob/main//build-git-connection.MD)
+- [3 - Install Node/NPM](https://github.com/samet-digital/help/blob/main//install-npm.MD)
+- [4 - Create Project Folder](https://github.com/samet-digital/help/blob/main//create-project-folder.MD)
+- [5 - Bind Projects Folder to Git](https://github.com/samet-digital/help/blob/main//bind-project-folder.MD)
+
+## Usage
+- `EN`: How to add into your project?
+- `TR`: Projene nasıl eklersin?
+
+```shell
+npm i @samet-it/be-db-common
+```
+
+## Environments
+- ~~Nothing~~
+
+## Contents
+- [abstract class DbConnection](./src/connection/db-connection.ts)
+- [function dbLines()](./src/line/db-lines.impl.ts)
+- [abstract class DbRepo](./src/repo/db.repo.ts)
+
+## Development
+> You can start to develop on it
+>
+### Step 1
+- [Go to project folder](https://github.com/samet-digital/help/blob/main/go-to-project-folder.MD)
+
+### Step 2
+- `EN`: Clone the project
+- `TR`: Projeyi bilgisayarına çek
+```shell
+git clone https://github.com/samet-digital/be-db-common.git -b development
+```
+
+## Dependencies
+- `@samet-it/be-base-common`:  **samet** base common
+- `@leyyo/*`: leyyo utilities
+
+## Commands
+- [Component Commands](https://github.com/samet-digital/help/blob/main/commands-component.MD)
+
+## Standards
+```diff
++ language: TS 
++ lint: eslint
++ inspections: intelli-j code inspections
++ ddd: domain driven development
++ edd: exception driven development
+! tdd: test driven development
++ ldd: log driven development
++ ddd: document driven development
+```
+
+## History
+| Date       | Developer      | Info         | Ticket         |
+|------------|----------------|--------------|----------------|
+| 2026-01-20 | Mustafa Yelmer | _Created_    | ~~[none](./)~~ |
+| 2025-01-24 | Mustafa Yelmer | _Refactored_ | ~~[none](./)~~ |

package/dist/connection/db.connection.d.ts

@@ -0,0 +1,74 @@
+import type { DbConnectionLike, DbExecOpt, DbQueryResultMore, DbQueryResultOne, DbConnOpt, DbMeta, DbOnAfter, DbConnProps } from "./index.types";
+import { LoggerLike } from "@samet-it/be-base-common";
+import type { DbLines } from "../line";
+import type { DbRepoDef } from "../repo";
+import type { Opt } from "@leyyo/common";
+/**
+ * DB connection abstract class
+ * */
+export declare abstract class DbConnection<REPO extends DbRepoDef, META extends DbMeta, OPT extends DbExecOpt> implements DbConnectionLike<REPO, META, OPT> {
+    /**
+     * Logger
+     * */
+    protected logger: LoggerLike;
+    /**
+     * On connected callbacks
+     * */
+    protected _onConnected: Array<DbOnAfter>;
+    /**
+     * On first connected callbacks
+     * */
+    protected _onFirstConnected: Array<DbOnAfter>;
+    /**
+     * On disconnected callbacks
+     * */
+    protected _onDisconnected: Array<DbOnAfter>;
+    /**
+     * Option of in-body usage in place of constructor param
+     * */
+    protected _opt: DbConnOpt;
+    /**
+     * Produced setting from option
+     * @see _opt
+     * */
+    protected _props: DbConnProps;
+    protected constructor(opt?: DbConnOpt);
+    checkError(err: Error, opt: DbExecOpt | Opt): void;
+    protected _on(items: Array<DbOnAfter>, fn: DbOnAfter, throwable: boolean): void;
+    /** {@inheritDoc} */
+    get props(): Readonly<DbConnProps>;
+    /** {@inheritDoc} */
+    f(field: string): string;
+    /** {@inheritDoc} */
+    abstract field(field: string): string;
+    v(value: unknown): string;
+    abstract value(value: unknown): string;
+    /** {@inheritDoc} */
+    rows<T>(rows: Array<T>): Array<T>;
+    /** {@inheritDoc} */
+    row<T>(row: T): T | undefined;
+    /** {@inheritDoc} */
+    first<T>(rows: Array<T>): T | undefined;
+    /** {@inheritDoc} */
+    buildOpt(p1?: Partial<OPT> | string, name?: string): OPT;
+    /** {@inheritDoc} */
+    onConnected(fn: DbOnAfter): void;
+    /** {@inheritDoc} */
+    onDisconnected(fn: DbOnAfter): void;
+    /** {@inheritDoc} */
+    onFirstConnected(fn: DbOnAfter): void;
+    /** {@inheritDoc} */
+    exec<T>(fn: Promise<T>, p1?: string | Omit<OPT, 'printSql'>): Promise<T>;
+    /** {@inheritDoc} */
+    abstract more<T>(repo: REPO, sql: string | DbLines, name?: string | DbExecOpt): Promise<DbQueryResultMore<T, META>>;
+    /** {@inheritDoc} */
+    abstract one<T>(repo: REPO, sql: string | DbLines, name?: string | DbExecOpt): Promise<DbQueryResultOne<T, META>>;
+    /**
+     * It will be called during module based systems
+     * */
+    onModuleInit(): Promise<void>;
+    /** {@inheritDoc} */
+    abstract ping(next?: boolean): Promise<boolean>;
+    /** {@inheritDoc} */
+    abstract connect(): Promise<boolean>;
+}

package/dist/connection/db.connection.js

@@ -0,0 +1,173 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbConnection = void 0;
+const be_base_common_1 = require("@samet-it/be-base-common");
+const type_1 = require("@leyyo/type");
+const error_1 = require("../error");
+// noinspection JSUnusedGlobalSymbols
+/**
+ * DB connection abstract class
+ * */
+class DbConnection {
+    // endregion protected-property
+    constructor(opt) {
+        /**
+         * On connected callbacks
+         * */
+        this._onConnected = [];
+        /**
+         * On first connected callbacks
+         * */
+        this._onFirstConnected = [];
+        /**
+         * On disconnected callbacks
+         * */
+        this._onDisconnected = [];
+        /**
+         * Option of in-body usage in place of constructor param
+         * */
+        this._opt = {};
+        if (!(0, type_1.isObjectBare)(this._opt)) {
+            this._opt = {};
+        }
+        if ((0, type_1.isObjectBare)(opt)) {
+            this._opt = Object.assign(Object.assign({}, this._opt), opt);
+        }
+        this._props = Object.assign({}, this._opt);
+        delete this._opt;
+    }
+    // region protected-method
+    checkError(err, opt) {
+        var _a, _b, _c;
+        const size = be_base_common_1.errorHandler.addStat(err);
+        if ((_a = opt === null || opt === void 0 ? void 0 : opt.ignoredErrors) === null || _a === void 0 ? void 0 : _a.includes(err.name)) {
+            return;
+        }
+        if (opt === null || opt === void 0 ? void 0 : opt.silent) {
+            if (size < 100) {
+                this.logger.warn(`[${size}] ${(_b = opt.name) !== null && _b !== void 0 ? _b : 'Database error'} <${err.name}> ${err.message}`, err);
+            }
+            return;
+        }
+        if (size < 100) {
+            this.logger.error(`[${size}] ${(_c = opt.name) !== null && _c !== void 0 ? _c : 'Database error'} <${err.name}> ${err.message}`, err);
+        }
+        if (err instanceof error_1.DbError) {
+            throw err;
+        }
+        else {
+            throw be_base_common_1.errorHandler.common.castForClass(error_1.DbError, err, { queryName: opt.name });
+        }
+    }
+    _on(items, fn, throwable) {
+        if (typeof fn !== 'function') {
+            return;
+        }
+        if (!this._props.isConnected) {
+            items.push(fn);
+        }
+        else {
+            fn().then().catch(e => {
+                this.logger.error(`[${e.name}] => ${e.message}`, e);
+                if (throwable) {
+                    throw e;
+                }
+            });
+        }
+    }
+    // endregion protected-method
+    // region getter
+    /** {@inheritDoc} */
+    get props() {
+        return this._props;
+    }
+    // endregion getter
+    // region field-value
+    /** {@inheritDoc} */
+    f(field) {
+        return this.field(field);
+    }
+    v(value) {
+        return this.value(value);
+    }
+    /** {@inheritDoc} */
+    rows(rows) {
+        if (rows && Array.isArray(rows) && (rows.length > 0)) {
+            return rows.filter(row => row['_trashId'] === undefined);
+        }
+        return [];
+    }
+    /** {@inheritDoc} */
+    row(row) {
+        if (row && row['_trashId'] === undefined) {
+            return row;
+        }
+        return undefined;
+    }
+    /** {@inheritDoc} */
+    first(rows) {
+        if (rows && Array.isArray(rows) && (rows.length > 0)) {
+            return rows[0];
+        }
+        return undefined;
+    }
+    // endregion field-value
+    // region option
+    /** {@inheritDoc} */
+    buildOpt(p1, name) {
+        const opt = (typeof p1 === 'string' ? { name: p1 } : Object.assign({}, p1));
+        if (typeof opt.name === undefined && typeof name !== undefined) {
+            opt.name = name;
+        }
+        opt.name = opt.name ? `[${opt.name}]` : '';
+        return opt;
+    }
+    // endregion option
+    // region callback
+    /** {@inheritDoc} */
+    onConnected(fn) {
+        this._on(this._onConnected, fn, false);
+    }
+    /** {@inheritDoc} */
+    onDisconnected(fn) {
+        this._on(this._onDisconnected, fn, false);
+    }
+    /** {@inheritDoc} */
+    onFirstConnected(fn) {
+        this._on(this._onFirstConnected, fn, true);
+    }
+    // endregion callback
+    // region query
+    /** {@inheritDoc} */
+    exec(fn, p1) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const opt = this.buildOpt(p1);
+            try {
+                return yield fn;
+            }
+            catch (err) {
+                this.checkError(err, opt);
+                return undefined;
+            }
+        });
+    }
+    // endregion query
+    /**
+     * It will be called during module based systems
+     * */
+    onModuleInit() {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield this.connect();
+        });
+    }
+}
+exports.DbConnection = DbConnection;

package/dist/connection/index.d.ts

@@ -0,0 +1,2 @@
+export * from './index.types';
+export * from './db.connection';

package/dist/connection/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./index.types"), exports);
+__exportStar(require("./db.connection"), exports);

package/dist/connection/index.types.d.ts

@@ -0,0 +1,294 @@
+import type { DbLines } from "../line";
+import type { DbRepoDef } from "../repo";
+import type { DbErrorOmit } from "../error";
+import { Opt } from "@leyyo/common";
+/**
+ * DB query result
+ * */
+export interface DbQueryResult<META> {
+    /**
+     * Success or failure
+     */
+    success: boolean;
+    /**
+     * [when success=true] The meta-data which has been returned by the query.
+     */
+    meta?: META;
+    /**
+     * [when success=false] Couchbase error
+     */
+    error?: DbErrorOmit;
+}
+/**
+ * DB query result as a row
+ * */
+export interface DbQueryResultOne<E = any, META = unknown> extends DbQueryResult<META> {
+    /**
+     * The rows which have been returned by the query.
+     */
+    row: E | undefined;
+}
+/**
+ * DB query result as rows
+ * */
+export interface DbQueryResultMore<E = any, META = unknown> extends DbQueryResult<META> {
+    /**
+     * The rows which have been returned by the query.
+     */
+    rows: E[];
+}
+/**
+ * DB query option
+ * */
+export interface DbExecOpt {
+    /**
+     * Name of SQL
+     * */
+    name?: string;
+    /**
+     * Ignored errors
+     * */
+    ignoredErrors?: Array<string>;
+    /**
+     * Print sql?
+     * */
+    printSql?: boolean;
+    /**
+     * Ignore any error
+     * */
+    silent?: boolean;
+    /**
+     * Trash id for only trash case
+     * */
+    trashId?: string;
+}
+/**
+ * DB connection
+ * */
+export interface DbConnectionBase<OPT extends DbExecOpt = DbExecOpt> {
+    /**
+     * Field name
+     *
+     * @param {string} field - raw field name
+     * @return {string} - formatted field name
+     * */
+    field(field: string): string;
+    /**
+     * Field name
+     * @alias #field
+     *
+     * @param {string} field - raw field name
+     * @return {string} - formatted field name
+     * */
+    f(field: string): string;
+    /**
+     * Format value
+     *
+     * @param {string} value - raw value
+     * @return {string} - formatted value
+     * */
+    value(value: unknown): string;
+    /**
+     * Format value
+     * @alias #value
+     *
+     * @param {string} value - raw value
+     * @return {string} - formatted value
+     * */
+    v(value: unknown): string;
+    /**
+     * Check rows and discard trashed
+     *
+     * @param {Array<any>} rows - rows
+     * @return {Array<any>} - checked rows
+     * */
+    rows<T>(rows: Array<T>): Array<T>;
+    /**
+     * Check row and discard trashed
+     *
+     * @param {any} row - row
+     * @return {any} - checked row
+     * */
+    row<T>(row: T): T | undefined;
+    /**
+     * Return first row of rows
+     *
+     * @param {Array<any>} rows - rows
+     * @return {any} - first row if exists
+     * */
+    first<T>(rows: Array<T>): T | undefined;
+    /**
+     * Build option
+     *
+     * @param {(DbExecOpt|string)?} opt - option or query name
+     * @param {string?} name - query name, if first param is option
+     * @return {DbExecOpt} - formatted option
+     * */
+    buildOpt(opt?: Partial<OPT> | string, name?: string): OPT;
+}
+/**
+ * DB connection interface
+ * */
+export interface DbConnectionLike<REPO extends DbRepoDef, META extends DbMeta, OPT extends DbExecOpt> extends DbConnectionBase {
+    /**
+     * Props on connection
+     * */
+    get props(): Readonly<DbConnProps>;
+    /**
+     * Add an async function into queue
+     *
+     * @param {function} fn - callback
+     * */
+    onFirstConnected(fn: DbOnAfter): void;
+    /**
+     * Add an async function into queue
+     *
+     * @param {function} fn - callback
+     * */
+    onConnected(fn: DbOnAfter): void;
+    /**
+     * Add an async function into queue
+     *
+     * @param {function} fn - callback
+     * */
+    onDisconnected(fn: DbOnAfter): void;
+    /**
+     * Check error
+     *
+     * @param {Error} err - error
+     * @param {DbExecOpt} opt - option
+     * */
+    checkError(err: Error, opt: DbExecOpt | Opt): void;
+    /**
+     * Execute a lambda
+     *
+     * @param {function} fn - promise callback
+     * @param {(DbExecOpt|string)?} opt - option or query name
+     * @return {Promise} - generic type
+     * @async
+     * */
+    exec<T>(fn: Promise<T>, opt?: string | Omit<OPT, 'printSql'>): Promise<T>;
+    /**
+     * Execute a sql and return rows
+     *
+     * @param {DbRepoLike} repo - repository instance
+     * @param {(string|DbLines)} sql - sql or sql lines
+     * @param {(DbExecOpt|string)?} opt - option or query name
+     * @return {Promise<DbQueryResultMore>} - rows
+     * @async
+     * */
+    more<T>(repo: REPO, sql: string | DbLines, opt?: string | OPT): Promise<DbQueryResultMore<T, META>>;
+    /**
+     * Execute a sql and return a row
+     *
+     * @param {DbRepoLike} repo - repository instance
+     * @param {(string|DbLines)} sql - sql or sql lines
+     * @param {(DbExecOpt|string)?} opt - option or query name
+     * @return {Promise<DbQueryResultOne>} - row
+     * @async
+     * */
+    one<T>(repo: REPO, sql: string | DbLines, opt?: string | OPT): Promise<DbQueryResultOne<T, META>>;
+    /**
+     * It will be called during module based systems
+     *
+     * @return {Promise<void>}
+     * @async
+     * */
+    onModuleInit(): Promise<void>;
+    /**
+     * Connect to DB
+     *
+     * @return {Promise<boolean>} - is success
+     * @async
+     * */
+    connect(): Promise<boolean>;
+    /**
+     * Ping to DB
+     * - Note: please give `true` fo only internal usage
+     *
+     * @param {boolean?} next - if true then it will continue to ping
+     * @return {Promise<boolean>} - is success?
+     * @async
+     * */
+    ping(next?: boolean): Promise<boolean>;
+}
+/**
+ * DB meta
+ * */
+export interface DbMeta {
+}
+/**
+ * DB connection option
+ * */
+export interface DbConnOpt {
+    /**
+     * Protocol
+     *
+     * @type {string}
+     * */
+    protocol?: string;
+    /**
+     * Host name or ip address
+     *
+     * @type {string}
+     * */
+    host?: string;
+    /**
+     * Port number
+     *
+     * @type {number}
+     * */
+    port?: number;
+    /**
+     * Username
+     *
+     * @type {string}
+     * */
+    username?: string;
+    /**
+     * Password
+     *
+     * @type {string}
+     * */
+    password?: string;
+    /**
+     * Environment variant to use other env keys in dependency injection
+     *
+     * @default `empty`
+     * @type {string}
+     * */
+    envVariant?: string;
+    /**
+     * User fetcher lambda
+     *
+     * @default `undefined`
+     * @type {function}
+     * */
+    userFetcher?: () => Promise<string>;
+}
+/**
+ * DB connection props
+ * */
+export interface DbConnProps extends DbConnOpt {
+    /**
+     * Is connected?
+     *
+     * @type {boolean}
+     * */
+    isConnected: boolean;
+    /**
+     * Is first connected?
+     *
+     * @type {boolean}
+     * */
+    isFirst: boolean;
+}
+/**
+ * DB on after lambda
+ * @function
+ * */
+export type DbOnAfter = () => Promise<void>;
+/**
+ * DB connection events
+ * */
+export type DbEvent = 'connected' | 'disconnected' | 'first-connected';

package/dist/connection/index.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/error/db-execute.error.d.ts

@@ -0,0 +1,5 @@
+import type { Opt } from "@leyyo/common";
+import { DbError } from "./db.error";
+export declare class DbExecuteError extends DbError {
+    constructor(err: Error, name: string, sql: string, opt?: Opt);
+}

package/dist/error/db-execute.error.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DbExecuteError = void 0;
+const db_error_1 = require("./db.error");
+class DbExecuteError extends db_error_1.DbError {
+    constructor(err, name, sql, opt) {
+        super(`${name ? name + ' : ' : ''}<${err.name}> ${err.message}`, Object.assign(Object.assign({}, opt), { sql, sqlName: name }));
+    }
+}
+exports.DbExecuteError = DbExecuteError;

package/dist/error/db-invalid-value.error.d.ts

@@ -0,0 +1,5 @@
+import type { BasicType } from "@leyyo/common";
+import { DbError } from "./db.error";
+export declare class DbInvalidValueError extends DbError {
+    constructor(field: string, type: BasicType, where: string, method: string);
+}