@oino-ts/db 0.0.11

package/dist/esm/OINODbApi.js

@@ -0,0 +1,265 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+import { OINODbDataModel, OINOStringDataField, OINO_ERROR_PREFIX, OINODbModelSet, OINOBenchmark, OINODbFactory, OINOLog, OINOResult } from "./index.js";
+import { OINOHashid } from "@oino-ts/hashid";
+/**
+ * OINO API request result object with returned data and/or http status code/message and
+ * error / warning messages.
+ *
+ */
+export class OINODbApiResult extends OINOResult {
+    /** Returned data if any */
+    data;
+    /**
+     * Constructor of OINODbApiResult.
+     *
+     * @param data result data
+     *
+     */
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+}
+/**
+ * API class with method to process HTTP REST requests.
+ *
+ */
+export class OINODbApi {
+    /** API database reference */
+    db;
+    /** API datamodel */
+    datamodel;
+    /** API parameters */
+    params;
+    /** API hashid */
+    hashid;
+    /**
+     * Constructor of API object.
+     * NOTE! OINODb.initDatamodel must be called if created manually instead of the factory.
+     *
+     * @param db database for the API
+     * @param params parameters for the API
+     *
+     */
+    constructor(db, params) {
+        // OINOLog.debug("OINODbApi.constructor", {db:db, tableName:tableName, params:params})
+        if (!params.tableName) {
+            throw new Error(OINO_ERROR_PREFIX + ": OINODbApiParams needs to define a table name!");
+        }
+        this.db = db;
+        this.params = params;
+        this.datamodel = new OINODbDataModel(this);
+        if (this.params.hashidKey) {
+            this.hashid = new OINOHashid(this.params.hashidKey, this.db.name, this.params.hashidLength, this.params.hashidRandomIds);
+        }
+        else {
+            this.hashid = null;
+        }
+    }
+    _validateRowValues(httpResult, row, requirePrimaryKey) {
+        let field;
+        for (let i = 0; i < this.datamodel.fields.length; i++) {
+            field = this.datamodel.fields[i];
+            // OINOLog.debug("OINODbApi.validateHttpValues", {field:field})
+            const val = row[i];
+            // OINOLog.debug("OINODbApi.validateHttpValues", {val:val})
+            if ((val === null) && ((field.fieldParams.isNotNull) || (field.fieldParams.isPrimaryKey))) { // null is a valid SQL value except if it's not allowed
+                httpResult.setError(405, "Field '" + field.name + "' is not allowed to be NULL!", "ValidateRowValues");
+            }
+            else if ((val === undefined) && (requirePrimaryKey) && (field.fieldParams.isPrimaryKey) && (!field.fieldParams.isAutoInc)) {
+                httpResult.setError(405, "Primary key '" + field.name + "' is not autoinc and missing from the data!", "ValidateRowValues");
+            }
+            else if ((val !== undefined) && (this.params.failOnUpdateOnAutoinc) && (field.fieldParams.isAutoInc)) {
+                httpResult.setError(405, "Autoinc field '" + field.name + "' can't be updated!", "ValidateRowValues");
+            }
+            else {
+                if ((field instanceof OINOStringDataField) && ((field.maxLength > 0))) {
+                    const str_val = val?.toString() || "";
+                    // OINOLog.debug("OINODbApi.validateHttpValues", {f:str_field, val:val})
+                    if (str_val.length > field.maxLength) {
+                        if (this.params.failOnOversizedValues) {
+                            httpResult.setError(405, "Field '" + field.name + "' length (" + str_val.length + ") exceeds maximum (" + field.maxLength + ") and can't be set!", "ValidateRowValues");
+                        }
+                        else {
+                            httpResult.addWarning("Field '" + field.name + "' length (" + str_val.length + ") exceeds maximum (" + field.maxLength + ") and might truncate or fail.", "ValidateRowValues");
+                        }
+                    }
+                }
+            }
+        }
+        //logDebug("OINODbApi.validateHttpValues", {result:result})
+    }
+    async _doGet(result, id, params) {
+        OINOBenchmark.start("doGet");
+        const sql = this.datamodel.printSqlSelect(id, params.sqlParams);
+        // OINOLog.debug("OINODbApi.doGet sql", {sql:sql})
+        try {
+            const sql_res = await this.db.sqlSelect(sql);
+            // OINOLog.debug("OINODbApi.doGet sql_res", {sql_res:sql_res})
+            if (sql_res.hasErrors()) {
+                result.setError(500, sql_res.getFirstError(), "DoGet");
+                result.addDebug("OINO GET SQL [" + sql + "]", "DoPut");
+            }
+            else {
+                result.data = new OINODbModelSet(this.datamodel, sql_res);
+            }
+        }
+        catch (e) {
+            result.setError(500, "Unhandled exception in doGet: " + e.message, "DoGet");
+            result.addDebug("OINO GET SQL [" + sql + "]", "DoGet");
+        }
+        OINOBenchmark.end("doGet");
+    }
+    async _doPost(result, rows) {
+        OINOBenchmark.start("doPost");
+        let sql = "";
+        try {
+            let i = 0;
+            while (i < rows.length) {
+                this._validateRowValues(result, rows[i], this.params.failOnInsertWithoutKey || false);
+                if (result.success) {
+                    sql += this.datamodel.printSqlInsert(rows[i]);
+                }
+                result.setOk(); // individual rows may fail and will just be messages in response similar to executing multiple sql statements
+                i++;
+            }
+            if (sql == "") {
+                result.setError(405, "No valid rows for POST!", "DoPost");
+                result.addDebug("OINO POST DATA [" + rows.join("|") + "]", "DoPost");
+            }
+            else {
+                // OINOLog.debug("OINODbApi.doPost sql", {sql:sql})
+                const sql_res = await this.db.sqlExec(sql);
+                // OINOLog.debug("OINODbApi.doPost sql_res", {sql_res:sql_res})
+                if (sql_res.hasErrors()) {
+                    result.setError(500, sql_res.getFirstError(), "DoPost");
+                    result.addDebug("OINO POST MESSAGES [" + sql_res.messages.join('|') + "]", "DoPost");
+                    result.addDebug("OINO POST SQL [" + sql + "]", "DoPost");
+                }
+            }
+        }
+        catch (e) {
+            result.setError(500, "Unhandled exception in doPost: " + e.message, "DoPost");
+            result.addDebug("OINO POST SQL [" + sql + "]", "DoPost");
+        }
+        OINOBenchmark.end("doPost");
+    }
+    async _doPut(result, id, row) {
+        OINOBenchmark.start("doPut");
+        let sql = "";
+        try {
+            this._validateRowValues(result, row, false);
+            if (result.success) {
+                sql = this.datamodel.printSqlUpdate(id, row);
+                // OINOLog.debug("OINODbApi.doPut sql", {sql:sql})
+                const sql_res = await this.db.sqlExec(sql);
+                // OINOLog.debug("OINODbApi.doPut sql_res", {sql_res:sql_res})
+                if (sql_res.hasErrors()) {
+                    result.setError(500, sql_res.getFirstError(), "DoPut");
+                    result.addDebug("OINO PUT MESSAGES [" + sql_res.messages.join('|') + "]", "DoPut");
+                    result.addDebug("OINO PUT SQL [" + sql + "]", "DoPut");
+                }
+            }
+        }
+        catch (e) {
+            result.setError(500, "Unhandled exception: " + e.message, "DoPut");
+            result.addDebug("OINO POST SQL [" + sql + "]", "DoPut");
+        }
+        OINOBenchmark.end("doPut");
+    }
+    async _doDelete(result, id) {
+        OINOBenchmark.start("doDelete");
+        let sql = "";
+        try {
+            sql = this.datamodel.printSqlDelete(id);
+            // OINOLog.debug("OINODbApi.doDelete sql", {sql:sql})
+            const sql_res = await this.db.sqlExec(sql);
+            // OINOLog.debug("OINODbApi.doDelete sql_res", {sql_res:sql_res})
+            if (sql_res.hasErrors()) {
+                result.setError(500, sql_res.getFirstError(), "DoDelete");
+                result.addDebug("OINO DELETE MESSAGES [" + sql_res.messages.join('|') + "]", "DoDelete");
+                result.addDebug("OINO DELETE SQL [" + sql + "]", "DoDelete");
+            }
+        }
+        catch (e) {
+            result.setError(500, "Unhandled exception: " + e.message, "DoDelete");
+            result.addDebug("OINO DELETE SQL [" + sql + "]", "DoDelete");
+        }
+        OINOBenchmark.end("doDelete");
+    }
+    /**
+     * Method for handlind a HTTP REST request with GET, POST, PUT, DELETE corresponding to
+     * SQL select, insert, update and delete.
+     *
+     * @param method HTTP verb (uppercase)
+     * @param id URL id of the REST request
+     * @param body HTTP body data as string
+     * @param params HTTP URL parameters as key-value-pairs
+     *
+     */
+    async doRequest(method, id, body, params) {
+        OINOBenchmark.start("doRequest");
+        let result = new OINODbApiResult();
+        OINOLog.debug("OINODbApi.doRequest enter", { method: method, id: id, body: body, searchParams: params });
+        if (method == "GET") {
+            await this._doGet(result, id, params);
+        }
+        else if (method == "PUT") {
+            const rows = OINODbFactory.createRows(this.datamodel, body, params);
+            if (!id) {
+                result.setError(400, "HTTP PUT method requires an URL ID for the row that is updated!", "DoRequest");
+            }
+            else if (rows.length != 1) {
+                result.setError(400, "HTTP PUT method requires exactly one row in the body data!", "DoRequest");
+            }
+            else {
+                try {
+                    await this._doPut(result, id, rows[0]);
+                }
+                catch (e) {
+                    result.setError(500, "Unhandled exception in HTTP PUT doRequest: " + e.message, "DoRequest");
+                }
+            }
+        }
+        else if (method == "POST") {
+            const rows = OINODbFactory.createRows(this.datamodel, body, params);
+            if (id) {
+                result.setError(400, "HTTP POST method must not have an URL ID as it does not target an existing row but creates a new one!", "DoRequest");
+            }
+            else if (rows.length == 0) {
+                result.setError(400, "HTTP POST method requires at least one row in the body data!", "DoRequest");
+            }
+            else {
+                try {
+                    OINOLog.debug("OINODbApi.doRequest / POST", { rows: rows });
+                    await this._doPost(result, rows);
+                }
+                catch (e) {
+                    result.setError(500, "Unhandled exception in HTTP POST doRequest: " + e.message, "DoRequest");
+                }
+            }
+        }
+        else if (method == "DELETE") {
+            if (!id) {
+                result.setError(400, "HTTP DELETE method requires an id!", "DoRequest");
+            }
+            else {
+                try {
+                    await this._doDelete(result, id);
+                }
+                catch (e) {
+                    result.setError(500, "Unhandled exception in HTTP DELETE doRequest: " + e.message, "DoRequest");
+                }
+            }
+        }
+        else {
+            result.setError(405, "Unsupported HTTP method '" + method + "'", "DoRequest");
+        }
+        OINOBenchmark.end("doRequest");
+        return result;
+    }
+}

package/dist/esm/OINODbConfig.js

@@ -0,0 +1,82 @@
+/** Set the name of the OINO ID field (default \_OINOID\_) */
+export class OINODbConfig {
+    /** Name of the synthetic OINO ID field */
+    static OINODB_ID_FIELD = "_OINOID_";
+    /** Private key separator of the synthetic OINO ID field */
+    static OINODB_ID_SEPARATOR = "_";
+    static OINODB_ID_SEPARATOR_ESCAPED = "%";
+    /** Name of the OINODbSqlFilter-parameter in request */
+    static OINODB_SQL_FILTER_PARAM = "oinosqlfilter";
+    /** Name of the OINODbSqlOrder-parameter in request */
+    static OINODB_SQL_ORDER_PARAM = "oinosqlorder";
+    /** Name of the OINODbSqlLimit-parameter in request */
+    static OINODB_SQL_LIMIT_PARAM = "oinosqllimit";
+    /**
+     * Set the name of the OINO ID field
+     * @param idField name of the OINO ID field
+     */
+    static setOinoIdField(idField) {
+        if (idField) {
+            OINODbConfig.OINODB_ID_FIELD = idField;
+        }
+    }
+    /**
+     * Set the separator character of the OINO ID field
+     * @param idSeparator character to use as separator of id parts
+    */
+    static setOinoIdSeparator(idSeparator) {
+        if (idSeparator && (idSeparator.length == 1)) {
+            OINODbConfig.OINODB_ID_SEPARATOR = idSeparator;
+            OINODbConfig.OINODB_ID_SEPARATOR_ESCAPED = '%' + idSeparator.charCodeAt(0).toString(16);
+        }
+    }
+    /**
+     * Print OINO ID for primary key values.
+     *
+     * @param primaryKeys an array of primary key values.
+     *
+     */
+    static printOINOId(primaryKeys) {
+        let result = "";
+        for (let i = 0; i < primaryKeys.length; i++) {
+            if (i > 0) {
+                result += OINODbConfig.OINODB_ID_SEPARATOR;
+            }
+            result += encodeURIComponent(primaryKeys[i]).replaceAll(OINODbConfig.OINODB_ID_SEPARATOR, OINODbConfig.OINODB_ID_SEPARATOR_ESCAPED);
+        }
+        return result;
+    }
+    /**
+     * Set the name of the OINODbSqlFilter-param field
+     *
+     * @param sqlFilterParam name of the http parameter with `OINODbSqlFilter` definition
+     *
+     */
+    static setOinoSqlFilterParam(sqlFilterParam) {
+        if (sqlFilterParam) {
+            OINODbConfig.OINODB_SQL_FILTER_PARAM = sqlFilterParam;
+        }
+    }
+    /**
+     * Set the name of the OINODbSqlOrder-param field
+     *
+     * @param sqlOrderParam name of the http parameter with `OINODbSqlOrder` definition
+     *
+     */
+    static setOinoSqlOrderParam(sqlOrderParam) {
+        if (sqlOrderParam) {
+            OINODbConfig.OINODB_SQL_ORDER_PARAM = sqlOrderParam;
+        }
+    }
+    /**
+     * Set the name of the OINODbSqlLimit-param field
+     *
+     * @param sqlLimitParam name of the http parameter with `OINODbSqlLimit` definition
+     *
+     */
+    static setOinoSqlLimitParam(sqlLimitParam) {
+        if (sqlLimitParam) {
+            OINODbConfig.OINODB_SQL_LIMIT_PARAM = sqlLimitParam;
+        }
+    }
+}

package/dist/esm/OINODbDataField.js

@@ -0,0 +1,345 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+/**
+ * Base class for a column of data responsible for appropriatelly serializing/deserializing the data.
+ *
+ */
+export class OINODbDataField {
+    /** OINODB reference*/
+    db;
+    /** Name of the field */
+    name;
+    /** Internal type of field*/
+    type;
+    /** SQL type of the field */
+    sqlType;
+    /** Maximum length of the field (or 0) */
+    maxLength;
+    /** Parameters for the field */
+    fieldParams;
+    /**
+     * Constructor for a data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param type internal type of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(db, name, type, sqlType, fieldParams, maxLength = 0) {
+        this.db = db;
+        this.name = name;
+        this.type = type;
+        this.maxLength = maxLength;
+        this.sqlType = sqlType;
+        this.fieldParams = fieldParams;
+        // OINOLog.debug("OINODbDataField.constructor", {this:this})
+    }
+    /**
+     * Pring debug information for the field
+     *
+     * @param length length of the debug output (or 0 for as long as needed)
+     *
+     */
+    printColumnDebug(length = 0) {
+        let params = "";
+        if (this.fieldParams.isPrimaryKey) {
+            params += "PK ";
+        }
+        if (this.fieldParams.isAutoInc) {
+            params += "AUTOINC ";
+        }
+        if (this.fieldParams.isNotNull) {
+            params += "NOTNUL ";
+        }
+        if (params != "") {
+            params = "{" + params.trim() + "}";
+        }
+        if (this.maxLength > 0) {
+            params = this.sqlType + "(" + this.maxLength + ")" + params;
+        }
+        else {
+            params = this.sqlType + params;
+        }
+        const name_length = length - 2 - 1 - params.length;
+        let result = this.name;
+        if (length > 0) {
+            if (result.length > name_length) {
+                result = result.substring(0, name_length - 2) + "..";
+            }
+            result = (result + ":" + params).padEnd(length - 2, " ");
+        }
+        else {
+            result = this.type + ":" + result + ":" + params;
+        }
+        return "[" + result + "]";
+    }
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal) {
+        cellVal = this.db.parseSqlValueAsCell(cellVal, this.sqlType);
+        if ((cellVal === null) || (cellVal === undefined)) {
+            return cellVal; // let content type encoder worry what to do with the value (so not force it to string)
+        }
+        else {
+            return cellVal.toString();
+        }
+    }
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value) {
+        return value;
+    }
+    /**
+     * Print data cell (from deserialization) as SQL-string.
+     *
+     * @param cellVal cell value
+     *
+     */
+    printCellAsSqlValue(cellVal) {
+        return this.db.printCellAsSqlValue(cellVal, this.sqlType);
+    }
+    /**
+     * Print name of column as SQL.
+     *
+     */
+    printSqlColumnName() {
+        return this.db.printSqlColumnname(this.name);
+    }
+}
+/**
+ * Specialised class for a string column.
+ *
+ */
+export class OINOStringDataField extends OINODbDataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(db, name, sqlType, fieldParams, maxLength) {
+        super(db, name, "string", sqlType, fieldParams, maxLength);
+    }
+}
+/**
+ * Specialised class for a boolean column.
+ *
+ */
+export class OINOBooleanDataField extends OINODbDataField {
+    /**
+     * Constructor for a boolean data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(db, name, sqlType, fieldParams) {
+        super(db, name, "boolean", sqlType, fieldParams);
+    }
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal) {
+        const parsed_value = (this.db.parseSqlValueAsCell(cellVal, this.sqlType) || "").toString();
+        let result;
+        // console.log("OINOBooleanDataField.serializeCell: parsed_value=" + parsed_value)
+        if ((parsed_value == "") || (parsed_value.toLowerCase() == "false") || (parsed_value.match(/^0+$/))) {
+            result = "false";
+        }
+        else {
+            result = "true";
+        }
+        return result;
+    }
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value) {
+        if (value == null || value == "" || value.toString().toLowerCase() == "false" || value == "0") { // TODO: testaa poistaa .toString()
+            return false;
+        }
+        else {
+            return true;
+        }
+    }
+}
+/**
+ * Specialised class for a number column.
+ *
+ */
+export class OINONumberDataField extends OINODbDataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(db, name, sqlType, fieldParams) {
+        super(db, name, "number", sqlType, fieldParams);
+    }
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal) {
+        let result;
+        if ((cellVal === null) || (cellVal === undefined) || (cellVal === "")) {
+            result = null;
+        }
+        else {
+            result = cellVal.toString();
+        }
+        return result;
+    }
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value) {
+        if (!value) {
+            return 0;
+        }
+        else {
+            return Number.parseFloat(value);
+        }
+    }
+}
+/**
+ * Specialised class for a blob column.
+ *
+ */
+export class OINOBlobDataField extends OINODbDataField {
+    /**
+     * Constructor for a blob data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(db, name, sqlType, fieldParams, maxLength) {
+        super(db, name, "blob", sqlType, fieldParams, maxLength);
+    }
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal) {
+        // OINOLog.debug("OINOBlobDataField.serializeCell", {cellVal:cellVal})
+        if ((cellVal === null) || (cellVal === undefined)) {
+            return cellVal;
+        }
+        else if (cellVal instanceof Uint8Array) {
+            return Buffer.from(cellVal).toString('base64');
+        }
+        else {
+            return cellVal.toString();
+        }
+    }
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value) {
+        if (value == null) {
+            return new Buffer(0);
+        }
+        else {
+            return Buffer.from(value, 'base64'); // Blob-field data is base64 encoded and converted internally to UInt8Array / Buffer
+        }
+    }
+}
+/**
+ * Specialised class for a datetime column.
+ *
+ */
+export class OINODatetimeDataField extends OINODbDataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(db, name, sqlType, fieldParams) {
+        super(db, name, "datetime", sqlType, fieldParams);
+    }
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal) {
+        // OINOLog.debug("OINODatetimeDataField.serializeCell", {cellVal:cellVal, type:typeof(cellVal)})
+        if (typeof (cellVal) == "string") {
+            cellVal = this.db.parseSqlValueAsCell(cellVal, this.sqlType);
+            // OINOLog.debug("OINODatetimeDataField.serializeCell parsed", {cellVal:cellVal, type:typeof(cellVal)})
+        }
+        if ((cellVal === null) || (cellVal === undefined)) {
+            return cellVal;
+        }
+        else if (cellVal instanceof Date) {
+            return cellVal.toISOString();
+        }
+        else {
+            return cellVal.toString();
+        }
+    }
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value) {
+        // OINOLog.debug("OINODatetimeDataField.deserializeCell", {strVal:strVal})
+        if ((value === null) || (value === undefined)) {
+            return value;
+        }
+        else {
+            return new Date(value);
+        }
+    }
+}