@oino-ts/common 0.21.1 → 1.0.0

package/src/OINOConfig.ts

@@ -0,0 +1,113 @@
+/** Set the name of the OINO ID field (default \_OINOID\_) */
+
+export class OINOConfig {
+    /** Name of the synthetic OINO ID field */
+    static OINO_ID_FIELD:string = "_OINOID_"
+    /** Private key separator of the synthetic OINO ID field */
+    static OINO_ID_SEPARATOR:string = "_"
+    private static OINO_ID_SEPARATOR_ESCAPED:string = "%5F" // url-encoded "_"
+
+    /** Name of the OINODbQueryFilter-parameter in request */
+    static OINO_QUERY_FILTER_PARAM:string = "oinoqueryfilter"
+
+    /** Name of the OINODbQueryOrder-parameter in request */
+    static OINO_QUERY_ORDER_PARAM:string = "oinoqueryorder"
+
+    /** Name of the OINODbQueryLimit-parameter in request */
+    static OINO_QUERY_LIMIT_PARAM:string = "oinoquerylimit"
+
+    /** Name of the OINODbQueryAggregate-parameter in request */
+    static OINO_QUERY_AGGREGATE_PARAM:string = "oinoqueryaggregate"
+
+    /** Name of the OINODbSqlSelect-parameter in request */
+    static OINO_QUERY_SELECT_PARAM:string = "oinoqueryselect"
+
+    /** 
+     * Set the name of the OINO ID field 
+     * @param idField name of the OINO ID field 
+     */
+    static setOinoIdField(idField: string) {
+        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: string) {
+        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:string[]):string {
+        let result:string = ""
+        for (let i=0; i< primaryKeys.length; i++) {
+            if (i > 0) {
+                result += OINOConfig.OINO_ID_SEPARATOR
+            } 
+            result += encodeURIComponent(primaryKeys[i] as string).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:string):string[] {
+        let result:string[] = []
+        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: string) {
+        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: string) {
+        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: string) {
+        if (sqlLimitParam) {
+            OINOConfig.OINO_QUERY_LIMIT_PARAM = sqlLimitParam;
+        }
+    }
+}

package/src/OINOConstants.ts

@@ -0,0 +1,59 @@
+/*
+ * 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"
+
+/** 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 enum OINOContentType { 
+    /** JSON encoded data */
+    json='application/json', 
+    /** CSV encoded data */
+    csv='text/csv', 
+    /** Multipart encoded form data */
+    formdata='multipart/form-data', 
+    /** URL encoded form data */
+    urlencode='application/x-www-form-urlencoded', 
+    /** HTML encoded data (output only) */
+    html='text/html' 
+}
+
+/** Field parameters in database */
+export type OINODataFieldParams = {
+    /** Is the field a primary key */
+    isPrimaryKey: boolean
+    /** Is the field a primary key */
+    isForeignKey: boolean
+    /** Is the field an auto inc type */
+    isAutoInc: boolean
+    /** Is the field allowed to have null values */
+    isNotNull: boolean
+}
+
+/** A single column value of a data row */
+export type OINODataCell = string | bigint | number | boolean | Date | Uint8Array | Buffer | null | undefined
+/** A single data row */
+export type OINODataRow = Array<OINODataCell>
+/** Empty row instance */
+export const OINO_EMPTY_ROW:OINODataRow = []
+/** Empty row array instance */
+export const OINO_EMPTY_ROWS:OINODataRow[] = []

package/src/OINODataField.ts

@@ -0,0 +1,371 @@
+/*
+ * 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, OINODataFieldParams, OINODataCell } from "./OINOConstants.js"
+import { OINOLog } from "./OINOLog.js"
+import { OINODataSource } from "./OINODataSource.js"
+
+/**
+ * Base class for a column of data responsible for appropriatelly serializing/deserializing the data.
+ *
+ */
+export class OINODataField {
+
+    /** OINO data source reference*/
+    readonly datasource:OINODataSource;
+
+    /** Name of the field */
+    readonly name: string;
+
+    /** Internal type of field*/
+    readonly type: string;
+
+    /** SQL type of the field */
+    readonly nativeType: string;
+
+    /** Maximum length of the field (or 0) */
+    readonly maxLength: number;
+
+    /** Parameters for the field */
+    readonly fieldParams: OINODataFieldParams;
+
+    /**
+     * 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:OINODataSource, name: string, type:string, nativeType: string, fieldParams: OINODataFieldParams, maxLength:number = 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: OINODataCell):string|null|undefined {
+        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: string|null|undefined): OINODataCell {
+        return value
+    }
+
+    /**
+     * Print data cell (from deserialization) as SQL-string.
+     * 
+     * @param cellVal cell value
+     *
+     */
+    printCellAsValue(cellVal: OINODataCell):string {
+        return this.datasource.printCellAsValue(cellVal, this.nativeType);
+    }
+
+    /**
+     * Print name of column as SQL.
+     * 
+     */
+    printColumnName():string {
+        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:OINODataSource, name: string, nativeType: string, fieldParams: OINODataFieldParams, maxLength: number) {
+        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:OINODataSource, name: string, nativeType: string, fieldParams: OINODataFieldParams) {
+        super(datasource, name, "boolean", nativeType, fieldParams)
+    }
+    /**
+     * Serialize cell value in the given content format.
+     * 
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal: OINODataCell):string|null|undefined {
+        const parsed_value:string = (this.datasource.parseValueAsCell(cellVal, this.nativeType) || "").toString()
+        let result:string
+        // 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: string|null|undefined): OINODataCell {
+        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:OINODataSource, name: string, nativeType: string, fieldParams: OINODataFieldParams) {
+        super(datasource, name, "number", nativeType, fieldParams)
+    }
+
+    /**
+     * Serialize cell value in the given content format.
+     * 
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal: OINODataCell):string|null|undefined {
+        let result:string|null
+        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: string|null|undefined): OINODataCell {
+        if (value === undefined) { 
+            return undefined
+        } else if ((value === "") || (value === null)) {
+            return null
+        } else {
+            const result:number = 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:OINODataSource, name: string, nativeType: string, fieldParams: OINODataFieldParams, maxLength:number) {
+        super(datasource, name, "blob", nativeType, fieldParams, maxLength)
+    }
+
+    /**
+     * Serialize cell value in the given content format.
+     * 
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal: OINODataCell):string|null|undefined {
+        // 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: string|null|undefined): OINODataCell {
+        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:OINODataSource, name: string, nativeType: string, fieldParams: OINODataFieldParams) {
+        super(datasource, name, "datetime", nativeType, fieldParams)
+    }
+
+    /**
+     * Serialize cell value in the given content format.
+     * 
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal: OINODataCell): string|null|undefined {
+        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: OINODataCell, locale:Intl.DateTimeFormat): string|null|undefined {
+        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: string|null|undefined): OINODataCell {
+        if ((value === null) || (value === undefined)) {
+            return value
+        } else {
+            return new Date(value)
+        }        
+    }
+    
+}
+
+/** 
+ * Callback to filter data fields 
+ * @param field fields to filter
+ */
+export type OINODataFieldFilter = (field:OINODataField) => Boolean