@oino-ts/common 0.21.1 → 1.0.0

package/dist/esm/OINOConfig.js

@@ -0,0 +1,100 @@
+/** Set the name of the OINO ID field (default \_OINOID\_) */
+export class OINOConfig {
+    /** Name of the synthetic OINO ID field */
+    static OINO_ID_FIELD = "_OINOID_";
+    /** Private key separator of the synthetic OINO ID field */
+    static OINO_ID_SEPARATOR = "_";
+    static OINO_ID_SEPARATOR_ESCAPED = "%5F"; // url-encoded "_"
+    /** Name of the OINODbQueryFilter-parameter in request */
+    static OINO_QUERY_FILTER_PARAM = "oinoqueryfilter";
+    /** Name of the OINODbQueryOrder-parameter in request */
+    static OINO_QUERY_ORDER_PARAM = "oinoqueryorder";
+    /** Name of the OINODbQueryLimit-parameter in request */
+    static OINO_QUERY_LIMIT_PARAM = "oinoquerylimit";
+    /** Name of the OINODbQueryAggregate-parameter in request */
+    static OINO_QUERY_AGGREGATE_PARAM = "oinoqueryaggregate";
+    /** Name of the OINODbSqlSelect-parameter in request */
+    static OINO_QUERY_SELECT_PARAM = "oinoqueryselect";
+    /**
+     * Set the name of the OINO ID field
+     * @param idField name of the OINO ID field
+     */
+    static setOinoIdField(idField) {
+        if (idField) {
+            OINOConfig.OINO_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)) {
+            OINOConfig.OINO_ID_SEPARATOR = idSeparator;
+            OINOConfig.OINO_ID_SEPARATOR_ESCAPED = '%' + idSeparator.charCodeAt(0).toString(16).toUpperCase();
+        }
+    }
+    /**
+     * 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 += OINOConfig.OINO_ID_SEPARATOR;
+            }
+            result += encodeURIComponent(primaryKeys[i]).replaceAll(OINOConfig.OINO_ID_SEPARATOR, OINOConfig.OINO_ID_SEPARATOR_ESCAPED); // force encoding of _ and other non-encoded separators
+        }
+        return result;
+    }
+    /**
+     * Print OINO ID for primary key values.
+     *
+     * @param oinoid the OINO ID string to parse as primary key values.
+     *
+     */
+    static parseOINOId(oinoid) {
+        let result = [];
+        const parts = oinoid.split(OINOConfig.OINO_ID_SEPARATOR);
+        for (const part of parts) {
+            result.push(decodeURIComponent(part));
+        }
+        return result;
+    }
+    /**
+     * Set the name of the OINODbQueryFilter-param field
+     *
+     * @param sqlFilterParam name of the http parameter with `OINODbQueryFilter` definition
+     *
+     */
+    static setOinoQueryFilterParam(sqlFilterParam) {
+        if (sqlFilterParam) {
+            OINOConfig.OINO_QUERY_FILTER_PARAM = sqlFilterParam;
+        }
+    }
+    /**
+     * Set the name of the OINODbQueryOrder-param field
+     *
+     * @param sqlOrderParam name of the http parameter with `OINODbQueryOrder` definition
+     *
+     */
+    static setOinoQueryOrderParam(sqlOrderParam) {
+        if (sqlOrderParam) {
+            OINOConfig.OINO_QUERY_ORDER_PARAM = sqlOrderParam;
+        }
+    }
+    /**
+     * Set the name of the OINODbQueryLimit-param field
+     *
+     * @param sqlLimitParam name of the http parameter with `OINODbQueryLimit` definition
+     *
+     */
+    static setOinoQueryLimitParam(sqlLimitParam) {
+        if (sqlLimitParam) {
+            OINOConfig.OINO_QUERY_LIMIT_PARAM = sqlLimitParam;
+        }
+    }
+}

package/dist/esm/OINOConstants.js

@@ -0,0 +1,39 @@
+/*
+ * 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/.
+ */
+/** OINO error message prefix */
+export const OINO_ERROR_PREFIX = "OINO ERROR";
+/** OINO warning message prefix */
+export const OINO_WARNING_PREFIX = "OINO WARNING";
+/** OINO info message prefix */
+export const OINO_INFO_PREFIX = "OINO INFO";
+/** OINO debug message prefix */
+export const OINO_DEBUG_PREFIX = "OINO DEBUG";
+/** Name of the OINOContentType-parameter request */
+export const OINO_REQUEST_TYPE_PARAM = "oinorequesttype";
+/** Name of the OINOContentType-parameter request */
+export const OINO_RESPONSE_TYPE_PARAM = "oinoresponsetype";
+/** Name of the query parameter that triggers a file download response */
+export const OINO_RESPONSE_DOWNLOAD_PARAM = "oinoresponsedownload";
+/**
+ * Supported content format mime-types
+ */
+export var OINOContentType;
+(function (OINOContentType) {
+    /** JSON encoded data */
+    OINOContentType["json"] = "application/json";
+    /** CSV encoded data */
+    OINOContentType["csv"] = "text/csv";
+    /** Multipart encoded form data */
+    OINOContentType["formdata"] = "multipart/form-data";
+    /** URL encoded form data */
+    OINOContentType["urlencode"] = "application/x-www-form-urlencoded";
+    /** HTML encoded data (output only) */
+    OINOContentType["html"] = "text/html";
+})(OINOContentType || (OINOContentType = {}));
+/** Empty row instance */
+export const OINO_EMPTY_ROW = [];
+/** Empty row array instance */
+export const OINO_EMPTY_ROWS = [];

package/dist/esm/OINODataField.js

@@ -0,0 +1,337 @@
+/*
+ * 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 { Buffer } from "node:buffer";
+import { OINO_ERROR_PREFIX } from "./OINOConstants.js";
+import { OINOLog } from "./OINOLog.js";
+/**
+ * Base class for a column of data responsible for appropriatelly serializing/deserializing the data.
+ *
+ */
+export class OINODataField {
+    /** OINO data source reference*/
+    datasource;
+    /** Name of the field */
+    name;
+    /** Internal type of field*/
+    type;
+    /** SQL type of the field */
+    nativeType;
+    /** Maximum length of the field (or 0) */
+    maxLength;
+    /** Parameters for the field */
+    fieldParams;
+    /**
+     * Constructor for a data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param type internal type of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(datasource, name, type, nativeType, fieldParams, maxLength = 0) {
+        this.datasource = datasource;
+        this.name = name;
+        this.type = type;
+        this.maxLength = maxLength;
+        this.nativeType = nativeType;
+        this.fieldParams = fieldParams;
+    }
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal) {
+        cellVal = this.datasource.parseValueAsCell(cellVal, this.nativeType);
+        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
+     *
+     */
+    printCellAsValue(cellVal) {
+        return this.datasource.printCellAsValue(cellVal, this.nativeType);
+    }
+    /**
+     * Print name of column as SQL.
+     *
+     */
+    printColumnName() {
+        return this.datasource.printColumnName(this.name);
+    }
+}
+/**
+ * Specialised class for a string column.
+ *
+ */
+export class OINOStringDataField extends OINODataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(datasource, name, nativeType, fieldParams, maxLength) {
+        super(datasource, name, "string", nativeType, fieldParams, maxLength);
+    }
+}
+/**
+ * Specialised class for a boolean column.
+ *
+ */
+export class OINOBooleanDataField extends OINODataField {
+    /**
+     * Constructor for a boolean data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(datasource, name, nativeType, fieldParams) {
+        super(datasource, name, "boolean", nativeType, fieldParams);
+    }
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal) {
+        const parsed_value = (this.datasource.parseValueAsCell(cellVal, this.nativeType) || "").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 OINODataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(datasource, name, nativeType, fieldParams) {
+        super(datasource, name, "number", nativeType, 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 === undefined) {
+            return undefined;
+        }
+        else if ((value === "") || (value === null)) {
+            return null;
+        }
+        else {
+            const result = parseFloat(value);
+            if (isNaN(result)) {
+                OINOLog.error("@oino-ts/db", "OINONumberDataField", "toSql", "Invalid value!", { value: value });
+                throw new Error(OINO_ERROR_PREFIX + ": OINONumberDataField.deserializeCell - Invalid value '" + value + "'"); // incorrectly formatted data could be a security risk, abort processing
+            }
+            return result;
+        }
+    }
+}
+/**
+ * Specialised class for a blob column.
+ *
+ */
+export class OINOBlobDataField extends OINODataField {
+    /**
+     * Constructor for a blob data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(datasource, name, nativeType, fieldParams, maxLength) {
+        super(datasource, name, "blob", nativeType, fieldParams, maxLength);
+    }
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal) {
+        // console.log("OINOBlobDataField.serializeCell: cellVal", cellVal, typeof(cellVal))
+        if ((cellVal === null) || (cellVal === undefined)) {
+            return cellVal;
+        }
+        else if (cellVal instanceof Buffer) {
+            return cellVal.toString('base64');
+        }
+        else if (cellVal instanceof Uint8Array) {
+            return Buffer.from(cellVal).toString('base64');
+        }
+        else {
+            return this.datasource.parseValueAsCell(cellVal, this.nativeType)?.toString();
+        }
+    }
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value) {
+        if (value == null) {
+            return Buffer.alloc(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 OINODataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(datasource, name, nativeType, fieldParams) {
+        super(datasource, name, "datetime", nativeType, fieldParams);
+    }
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal) {
+        if (typeof (cellVal) == "string") {
+            cellVal = this.datasource.parseValueAsCell(cellVal, this.nativeType);
+        }
+        if ((cellVal === null) || (cellVal === undefined)) {
+            return cellVal;
+        }
+        else if (cellVal instanceof Date) {
+            return cellVal.toISOString();
+        }
+        else {
+            return cellVal.toString();
+        }
+    }
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     * @param locale locale-object to format datetimes with
+     *
+     */
+    serializeCellWithLocale(cellVal, locale) {
+        if (typeof (cellVal) == "string") {
+            cellVal = this.datasource.parseValueAsCell(cellVal, this.nativeType);
+        }
+        if ((cellVal === null) || (cellVal === undefined)) {
+            return cellVal;
+        }
+        else if (cellVal instanceof Date) {
+            return locale.format(cellVal);
+        }
+        else {
+            return cellVal.toString();
+        }
+    }
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value) {
+        if ((value === null) || (value === undefined)) {
+            return value;
+        }
+        else {
+            return new Date(value);
+        }
+    }
+}

package/dist/esm/OINODataModel.js

@@ -0,0 +1,178 @@
+/*
+ * 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 { OINONumberDataField } from "./OINODataField.js";
+/**
+ * OINO Datamodel object for representing one database table and it's columns.
+ *
+ */
+export class OINODataModel {
+    _fieldIndexLookup;
+    /** Database refererence of the table */
+    api;
+    /** Field refererences of the API */
+    fields;
+    /**
+     * Constructor of the data model.
+     * NOTE! OINODbDataModel.initialize must be called after constructor to populate fields.
+     *
+     * @param api api of the data model
+     *
+     */
+    constructor(api) {
+        this._fieldIndexLookup = {};
+        this.api = api;
+        this.fields = [];
+    }
+    /**
+     * Add a field to the datamodel.
+     *
+     * @param field dataset field
+     *
+     */
+    addField(field) {
+        this.fields.push(field);
+        this._fieldIndexLookup[field.name] = this.fields.length - 1;
+    }
+    /**
+     * Find a field of a given name if any.
+     *
+     * @param name name of the field to find
+     *
+     */
+    findFieldByName(name) {
+        const i = this._fieldIndexLookup[name];
+        if (i >= 0) {
+            return this.fields[i];
+        }
+        else {
+            return null;
+        }
+    }
+    /**
+     * Find index of a field of a given name if any.
+     *
+     * @param name name of the field to find
+     *
+     */
+    findFieldIndexByName(name) {
+        const i = this._fieldIndexLookup[name];
+        if (i >= 0) {
+            return i;
+        }
+        else {
+            return -1;
+        }
+    }
+    /**
+     * Find all fields based of given filter callback criteria (e.g. fields of certain data type, primary keys etc.)
+     *
+     * @param filter callback called for each field to include or not
+     *
+     */
+    filterFields(filter) {
+        let result = [];
+        for (let f of this.fields) {
+            if (filter(f)) {
+                result.push(f);
+            }
+        }
+        return result;
+    }
+    /**
+     * Return the primary key values of one row in order of the data model
+     *
+     * @param row data row
+     * @param hashidValues apply hashid when applicable
+     *
+     */
+    getRowPrimarykeyValues(row, hashidValues = false) {
+        let values = [];
+        for (let i = 0; i < this.fields.length; i++) {
+            const f = this.fields[i];
+            if (f.fieldParams.isPrimaryKey) {
+                const value = row[i]?.toString() || "";
+                if (hashidValues && value && (f instanceof OINONumberDataField) && this.api.hashid) {
+                    values.push(this.api.hashid.encode(value));
+                }
+                else {
+                    values.push(value);
+                }
+            }
+        }
+        return values;
+    }
+    /**
+     * Pring debug information for the field
+     *
+     * @param length length of the debug output (or 0 for as long as needed)
+     *
+     */
+    printColumnDebug(field, length = 0) {
+        let params = "";
+        if (field.fieldParams.isPrimaryKey) {
+            params += "PK ";
+        }
+        if (field.fieldParams.isForeignKey) {
+            params += "FK ";
+        }
+        if (field.fieldParams.isAutoInc) {
+            params += "AUTOINC ";
+        }
+        if (field.fieldParams.isNotNull) {
+            params += "NOTNUL ";
+        }
+        if (params != "") {
+            params = "{" + params.trim() + "}";
+        }
+        if (field.maxLength > 0) {
+            params = field.nativeType + "(" + field.maxLength + ")" + params;
+        }
+        else {
+            params = field.nativeType + params;
+        }
+        const name_length = length - 2 - 1 - params.length;
+        let result = field.name;
+        if (length > 0) {
+            if (result.length > name_length) {
+                result = result.substring(0, name_length - 2) + "..";
+            }
+            result = (result + ":" + params).padEnd(length - 2, " ");
+        }
+        else {
+            result = field.type + ":" + result + ":" + params;
+        }
+        return "[" + result + "]";
+    }
+    /**
+     * Print debug information about the fields.
+     *
+     * @param separator string to separate field prints
+     *
+     */
+    printDebug(separator = "") {
+        let result = this.api.params.tableName + ":" + separator;
+        for (let f of this.fields) {
+            result += this.printColumnDebug(f) + separator;
+        }
+        return result;
+    }
+    /**
+     * Print all public properties (db, table name, fields) of the datamodel. Used
+     * in automated testing validate schema has stayed the same.
+     *
+     */
+    printFieldPublicPropertiesJson() {
+        const result = JSON.stringify(this.fields, (key, value) => {
+            if (key.startsWith("_")) {
+                return undefined;
+            }
+            else {
+                return value;
+            }
+        });
+        return result;
+    }
+}