db-crud-wrapper 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+## v0.1.0 (2022-12-08)
+
+    Initial release
+## v0.1.1 (2023-01-01)
+
+    Bug fix:
+        - default server/database
+## v0.1.4 (2024-02-24)
+
+    Bug fix:
+        - update mssql to 9.3.2
+        - update uuid to 9.0.1
+## v0.1.5 (2024-03-03)
+
+    Bug fix:
+        - deleteById function crash 
+        - new function return undefined
+        ## v0.1.5 (2024-03-03)
+## v0.1.6 (2024-03-03)
+
+    Bug fix:
+        - update function crash with date value
+## v0.1.9 (2024-03-12)
+
+    Added:
+        - execute store procedure
+## v0.2.0 (2024-04-02)
+
+    Changes:
+        - parameters position have been change for some api 
+    Added:
+        - batch job that run multiple instructions
+## v0.2.1 (2024-12-05)
+
+    Refresh dependency
+## v0.3.0 (2024-12-28)
+
+    Changes:
+        - execute api definition
+    Added:
+        - support for mySQL
+## v0.3.1 (2025-01-01)
+
+    Bug fix:
+        - autoId flag not onored
+## v0.3.11 (2025-10-25)
+
+    Added:
+        - testConnection()
+## v0.3.13 (2025-11-04)
+
+    Bug fix:
+        - mssql
+## v0.3.14 (2025-11-08)
+
+    Bug fix:
+        - getByFilters can return an object instead of array
+## v0.3.15 (2025-11-10)
+
+    Added:
+        - config
+        - log via callback        
+## v0.3.18 (2025-12-12)
+
+    Added:
+        - sessionStore
+## v0.3.24 (2025-12-21)
+
+    Added:
+        - appLog patameter
+        - delById(id, Ope) 
+## v0.3.30 (2026-01-06)
+
+    Bug fix:
+        - use timezone: 'Z' in mysql connection
+## v1.0.1 (2026-05-17)
+
+    Changes:
+        - adopt fluent sintax: get('table1').byId('001').execute()

package/README.md

@@ -0,0 +1,96 @@
+# db-crud-wrapper
+    CRUD api for database tables.
+
+## Installation
+    npm install db-crud-wrapper
+
+# Usage
+
+## Fluent API
+```javascript
+    import dbw from "db-crud-wrapper";
+
+    // define server and default database
+    const myDB = dbw.server("server1")
+        .user("myUser")
+        .password("myUserPassword")
+        .type(my-sql)           // my-sql, ms-sql, ...
+        .database("db1");       // .database() must be the last metod
+
+    // NOTE: the fluent API returns operation-specific builders.
+    // Example: .top() exists only on get queries, so calling it on put/patch/delete is not possible.
+    const myObj = dbw
+        .get("table1")                          // table name
+        .fields("Id", "OrderNumber")            // fields
+        .top(10)
+        .filters("OrderType in ('P', 'A')", "and", "OrderDate > '2022-12-01'") // can be: single string, multiple params, or array
+        .orderby("OrderDate desc");             // can be: single string, multiple params, or array
+    const myResult = await myObj.execute();
+
+    const myResult = await dbw
+        .get("db2.table2")
+        .fields("Id", "OrderNumber")
+        .byId("xxxxx-xxxxx-xxxxxxxxxxxx-xxxxxx")
+        .orderby("OrderDate desc")
+        .execute();
+
+    // insert
+    const myResult = await dbw
+        .post("table2")
+        .values({ OrderId: "xxxxx", RowSeq: 1 })
+        .execute();
+
+    // update
+    const myResult = await dbw
+        .patch("table2")
+        .values({ ItemRef: "2024-TX-0001" })
+        .byId("xxxxx")
+        .execute();
+    const myResult = await dbw
+        .patch("db2.table2")
+        .values({ ItemRef: "2024-TX-0001" })
+        .filters("OrderId = 'xxxxx'")
+        .execute();
+
+    // upsert
+    const myResult = await dbw
+        .put("table2")
+        .values({ OrderId: "xxxxx", RowSeq: 1 })
+        .byId("xxxxx")
+        .execute();
+
+    // delete
+    const myReult = await dbw
+        .del("table2")
+        .byId("xxxxx")
+        .execute();
+    const myReult = await dbw
+        .del("db2.table2")
+        .filters("OrderId = 'xxxxx'")
+        .execute();
+```
+
+License
+-------
+
+    MIT License
+
+    Copyright (c) 2022
+
+    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.

package/index.js

@@ -0,0 +1,5 @@
+"use strict";
+
+import * as factory from "./lib/factory.js";
+
+export default factory;

package/lib/builder.js

@@ -0,0 +1,404 @@
+'use strict';
+
+import * as f from './f.js';
+import * as dbOpe from './db-operations.js';
+import { config } from './config.js';
+
+
+function normalizeToArray(...values) {
+    const result = [];
+    values.forEach((value) => {
+        if (Array.isArray(value)) result.push(...value.filter((v) => v !== undefined && v !== null && v !== ''));
+        else if (value !== undefined && value !== null && value !== '') result.push(value);
+    });
+    return result;
+}
+
+function isQueryObject(obj) {
+        if (typeof obj !== 'object') throw new Error('Object not valid.');
+        if (!obj._operation || !obj._request[obj._operation]) throw new Error('Object not valid, missing operation get/post/put/patch/delete/...');
+        return true
+}
+
+export function parseObject(obj) {
+    if (isQueryObject(obj)) {
+        switch (obj._operation) {
+            case 'command':
+                return new CommandBuilder(obj)
+            case 'get':
+                return new GetBuilder(obj)
+            case 'post':
+                return new PostBuilder(obj)
+            case 'put':
+                return new PutBuilder(obj)
+            case 'patch':
+                return new PatchBuilder(obj)
+            case 'delete':
+                return new DeleteBuilder(obj)
+            case 'begin':
+                return new BeginBuilder(obj)
+            case 'commit':
+                return new CommitBuilder(obj)
+            case 'batch':
+                return new BatchBuilder(obj)
+            case 'passthrough':
+                return new PassthroughBuilder(obj)
+            default:
+                throw new Error('Operation not valid, must be one of get/post/put/patch/delete/...');
+        }
+    }
+}
+
+class BaseQueryBuilder {
+
+    constructor(tableOrCommand, operation) {
+
+        if (operation === undefined || operation === null || operation === '') 
+            throw new Error('Missing operation get/post/put/patch/delete/...');
+        this._operation = operation;
+    
+        this._request = {};
+        if (typeof tableOrCommand === 'object' && tableOrCommand._request && tableOrCommand._request[this._operation]) 
+            this._request[this._operation] = structuredClone(tableOrCommand._request[this._operation]);
+        else
+            this._request[this._operation] = {};
+    
+        if (typeof tableOrCommand === 'object') 
+            this._tableOrCommand = tableOrCommand._tableOrCommand
+        else 
+            this._tableOrCommand = tableOrCommand
+        if (!['begin', 'commit', 'rollback', 'batch', 'passthrough'].includes(this._operation)) {
+            if (this._tableOrCommand === undefined || this._tableOrCommand === null || this._tableOrCommand === '') 
+                throw new Error('Missing table or command.');
+        }
+
+    } 
+
+    #getSchema(operation, tableOrCommand) {
+        switch (operation) {
+        case 'command':
+            return dbOpe.prepareSchema(tableOrCommand, dbOpe.objectType.procedure)
+        case 'get':
+        case 'post':
+        case 'put':
+        case 'patch':
+        case 'delete':
+            return dbOpe.prepareSchema(tableOrCommand, dbOpe.objectType.table)
+        default:
+            return dbOpe.prepareSchema(undefined, undefined);
+        }
+    }
+
+    params(params) {
+        if (!params) return this;
+        if (!this._operation || !this._request[this._operation]) throw new Error('Missing operation type get/post/put/patch/delete/...');
+        this._request[this._operation].params = params;
+        return this;
+    }
+
+    log(log) {
+        this._request.appLog = log;
+        return this;
+    }
+
+    toObject() {
+        return {
+            _operation: this._operation,
+            _tableOrCommand: this._tableOrCommand,
+            _request: structuredClone(this._request),
+        };
+    }
+
+    async execute(rawResult = false) {
+
+        // some check
+        if (!this._operation || !this._request[this._operation]) 
+            throw new Error('Missing operation get/post/put/patch/delete/...');
+        if (!['get', 'delete', 'patch', 'put', 'post', 'command', 'batch', 'passthrough'].includes(this._operation)) 
+            throw new Error(`Operation '${this._operation}' not supported.`);
+        if (!this._tableOrCommand && (['get', 'delete', 'patch', 'put', 'post', 'command'].includes(this._operation))) 
+            throw new Error('Missing table or command.');
+        if ((this._operation === 'patch' || this._operation === 'put' || this._operation === 'post') && !this._request[this._operation]?.values) {
+            throw new Error('Missing values property. Use .values({...}) before execute().');
+        }
+
+        // prepare 
+        let dbOpeReq = undefined;  // can be an array or a string
+        if (this._operation === 'batch') {
+            dbOpeReq = this._request[this._operation].items.map((_item) => {
+                const _schema = this.#getSchema(_item._operation, _item._tableOrCommand)
+                const _connection = dbOpe.prepareConnection(_schema);
+                return dbOpe.prepareRun(_schema, _connection, { ..._item._request });
+            });
+        }
+        else if (this._operation === 'passthrough') {
+            const _schema = this.#getSchema(undefined, undefined)
+            const _connection = dbOpe.prepareConnection(_schema);
+            dbOpeReq = dbOpe.prepareRun(_schema, _connection, { ...this._request });
+        }
+        else {
+            const _schema = this.#getSchema(this._operation, this._tableOrCommand)
+            const _connection = dbOpe.prepareConnection(_schema);
+            dbOpeReq = dbOpe.prepareRun(_schema, _connection, { ...this._request });
+        }
+
+        // run (dbOpeReq should be an array or a string)
+        const _result = await dbOpe.runQuery(dbOpeReq, rawResult);
+
+        // if get.byId return a single object
+        if (!rawResult && this._operation === 'get' && this._request[this._operation].byId) {
+            return Array.isArray(_result) ? _result[0] : _result;
+        }
+        
+        return _result;
+
+    }
+
+}
+
+export class GetBuilder extends BaseQueryBuilder {
+    constructor(nameOrObject) {
+        super(nameOrObject, 'get');
+    }
+
+    fields(...fields) {
+        const normalizedFields = normalizeToArray(...fields);
+        if (normalizedFields.length === 0) this._request[this._operation].fields = undefined
+        else this._request[this._operation].fields = normalizedFields;
+        return this;
+    }
+
+    top(value) {
+        if (value === undefined || value === null || value === '') return this;
+        this._request[this._operation].options = `top ${value}`;
+        return this;
+    }
+
+    filters(...filters) {
+        const normalizedFilters = normalizeToArray(...filters);
+        if (normalizedFilters.length === 0) this._request[this._operation].filters = undefined
+        else this._request[this._operation].filters = normalizedFilters;
+        return this;
+    }
+
+    byId(idValue) {
+        this._request[this._operation].byId = idValue;
+        return this;
+    }
+
+    groupBy(...fields) {
+        const normalizedFields = normalizeToArray(...fields);
+        if (normalizedFields.length === 0) this._request[this._operation].groupBy = undefined
+        else this._request[this._operation].groupBy = normalizedFields;
+        return this;
+    }
+
+    groupFilters(...fields) {
+        const normalizedFields = normalizeToArray(...fields);
+        if (normalizedFields.length === 0) this._request[this._operation].groupFilters = undefined
+        else this._request[this._operation].groupFilters = normalizedFields;
+        return this;
+    }
+
+    orderBy(...fields) {
+        const normalizedFields = normalizeToArray(...fields);
+        if (normalizedFields.length === 0) this._request[this._operation].orderBy = undefined
+        else this._request[this._operation].orderBy = normalizedFields;
+        return this;
+    }
+}
+
+// post add a new record
+export class PostBuilder extends BaseQueryBuilder {
+    constructor(tablePath) {
+        super(tablePath, 'post');
+    }
+
+    values(values) {
+        this._request[this._operation].values = values;
+        return this;
+    }
+
+    byId(idValue) {
+        this._request[this._operation].byId = idValue;
+        return this;
+    }
+
+}
+
+// put try to update, if no records effected and byId is requested, then add a new record
+export class PutBuilder extends BaseQueryBuilder {
+    constructor(tablePath) {
+        super(tablePath, 'put');
+    }
+
+    values(values) {
+        this._request[this._operation].values = values;
+        return this;
+    }
+
+    filters(...filters) {
+        const normalizedFilters = normalizeToArray(...filters);
+        if (normalizedFilters.length === 0) this._request[this._operation].filters = undefined
+        else this._request[this._operation].filters = normalizedFilters;
+        return this;
+    }
+
+    byId(idValue) {
+        this._request[this._operation].byId = idValue;
+        return this;
+    }
+
+    async execute(rawResult = false) {
+        // try to update
+        let _result = await super.execute(rawResult);
+        
+        // if no records effected and byId is requested, then try to insert
+        if (_result === 0 && (this._request[this._operation].byId ?? '') !== '') {
+            _result = await new PostBuilder(this._tableOrCommand)
+                .values(this._request[this._operation].values)
+                .log(this._request.appLog)
+                .byId(this._request[this._operation].byId)
+                .execute(rawResult); 
+        }
+
+        return _result;
+    }
+
+}
+
+// patch update the record/s
+export class PatchBuilder extends BaseQueryBuilder {
+    constructor(tablePath) {
+        super(tablePath, 'patch');
+    }
+
+    values(values) {
+        this._request[this._operation].values = values;
+        return this;
+    }
+
+    filters(...filters) {
+        const normalizedFilters = normalizeToArray(...filters);
+        if (normalizedFilters.length === 0) this._request[this._operation].filters = undefined
+        else this._request[this._operation].filters = normalizedFilters;
+        return this;
+    }
+
+    byId(idValue) {
+        this._request[this._operation].byId = idValue;
+        return this;
+    }
+}
+
+// remove record/s
+export class DeleteBuilder extends BaseQueryBuilder {
+    constructor(tablePath) {
+        super(tablePath, 'delete');
+    }
+
+    filters(...filters) {
+        const normalizedFilters = normalizeToArray(...filters);
+        if (normalizedFilters.length === 0) this._request[this._operation].filters = undefined
+        else this._request[this._operation].filters = normalizedFilters;
+        return this;
+    }
+
+    byId(idValue) {
+        this._request[this._operation].byId = idValue;
+        return this;
+    }
+}
+
+// exec/call a store procedure
+export class CommandBuilder extends BaseQueryBuilder {
+
+    constructor(command) {
+        super(command, 'command');
+    }
+
+    arguments(...cmdArguments) {
+        const normalizedArguments = normalizeToArray(...cmdArguments);
+        if (normalizedArguments.length === 0) this._request[this._operation].arguments = undefined
+        else this._request[this._operation].arguments = normalizedArguments;
+        return this;
+    }
+
+}
+
+// begin transaction
+class BeginBuilder extends BaseQueryBuilder {
+    constructor() {
+        super(undefined, 'begin');
+    }
+}
+
+// commit transaction
+class CommitBuilder extends BaseQueryBuilder {
+    constructor() {
+        super(undefined, 'commit');
+    }
+}
+
+// rollback transaction
+class RollbackBuilder extends BaseQueryBuilder {
+    constructor() {
+        super(undefined, 'rollback');
+    }
+}
+
+// passthrough, run a raw query
+export class PassthroughBuilder extends BaseQueryBuilder {
+    constructor(command) {
+        // for passthrough don't set tableOrCommand but put command in the request.command property
+        if (typeof command === 'object')
+            super(command, 'passthrough')
+        else
+            super(undefined, 'passthrough')
+        this._request[this._operation].command = command;
+    }
+}
+
+// batch is an array of operations (get/put/post/...)  
+export class BatchBuilder extends BaseQueryBuilder {
+
+    constructor() {
+        super(undefined, 'batch');
+        this._request[this._operation].items = [];
+        this._request[this._operation].useTransaction = false;
+    }
+
+    useTransaction(useTransaction) {
+        if (typeof(useTransaction) === "boolean") 
+            this._request[this._operation].useTransaction = useTransaction;
+        return this;
+    }
+
+    // run batch
+    async execute(rawResult = false) {
+
+        if (this._request[this._operation].items.length == 0) 
+            throw new Error("There are not operations in this batch.");
+
+        // prepare transaction
+        if (this._request[this._operation].useTransaction) {
+            this._request[this._operation].items.unshift(new BeginBuilder().toObject());    
+            this._request[this._operation].items.push(new CommitBuilder().toObject());    
+        }
+
+        // run
+        // const _return = this._request[this._operation].items;
+        return await super.execute(rawResult);
+
+    }
+
+    // add operations 
+    add(...obj) {
+        for (const _obj of obj) {
+            if (isQueryObject(_obj)) 
+                this._request[this._operation].items.push(structuredClone(_obj));
+        }
+        return this;
+    }
+
+}