@oino-ts/types 0.0.11

package/src/OINOBenchmark.ts

@@ -0,0 +1,68 @@
+/*
+ * 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/.
+ */
+
+/**
+ * Static class for benchmarking functions.
+ *
+ */
+export class OINOBenchmark {
+
+    private static _benchmarkCount:Record<string, number> = {}
+    private static _benchmarkData:Record<string, number> = {}
+    private static _benchmarkEnabled:Record<string, boolean> = {}
+    private static _benchmarkStart:Record<string, number> = {}
+
+    /**
+     * Reset benchmark data (but not what is enabled).
+     *
+     */
+    static reset() {
+        this._benchmarkData = {}
+        this._benchmarkCount = {}
+    }
+
+    /**
+     *  Set benchmark names that are enabled.
+     *
+     *  @param names array of those benchmarks that are enabled 
+     */
+    static setEnabled(names:string[]):void {
+        this._benchmarkEnabled = {}
+        names.forEach(name => {
+            this._benchmarkEnabled[name] = true        
+        });
+    }
+
+    /**
+     * Start benchmark timing.
+     *
+     * @param name of the benchmark
+     */
+    static start(name:string):void {
+        if (this._benchmarkEnabled[name]) {
+            if (this._benchmarkCount[name] == undefined) {
+                this._benchmarkCount[name] = 0
+                this._benchmarkData[name] = 0
+            }
+            this._benchmarkStart[name] = performance.now()
+        }
+    }
+
+    /**
+     * Complete benchmark timing
+     * 
+     * @param name of the benchmark
+     */
+    static end(name:string):number {
+        let result:number = 0
+        if (this._benchmarkEnabled[name]) {
+            this._benchmarkCount[name] += 1
+            this._benchmarkData[name] += performance.now() - this._benchmarkStart[name]
+            result = this._benchmarkData[name] / this._benchmarkCount[name]
+        }
+        return result
+    }
+}

package/src/OINOLog.ts

@@ -0,0 +1,160 @@
+/*
+ * 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/.
+ */
+
+/** Logging levels */
+export enum OINOLogLevel { 
+    /** Debug messages */
+    debug=0, 
+    /** Informational messages */
+    info=1, 
+    /** Warning messages */
+    warn=2, 
+    /** Error messages */
+    error=3 
+}
+
+/**
+ * Abstract base class for logging implementations supporting 
+ * - error, warning, info and debug channels
+ * - setting level of logs outputted
+ *
+ */
+
+export abstract class OINOLog {
+    protected static _instance:OINOLog
+
+    protected _logLevel:OINOLogLevel = OINOLogLevel.warn
+
+    /**
+     * Abstract logging method to implement the actual logging operation.
+     * 
+     * @param logLevel level of the log events
+     *
+     */
+    constructor (logLevel:OINOLogLevel = OINOLogLevel.warn) {
+        // console.log("OINOLog.constructor: logLevel=" + logLevel)
+        this._logLevel = logLevel
+    }
+
+
+    /**
+     * Abstract logging method to implement the actual logging operation.
+     * 
+     * @param levelStr level string of the log event
+     * @param message message of the log event
+     * @param data structured data associated with the log event
+     *
+     */
+    protected abstract _writeLog(levelStr:string, message:string, data?:any):void
+
+    /**
+     * Abstract logging method to implement the actual logging operation.
+     * 
+     * @param level level of the log event
+     * @param levelStr level string of the log event
+     * @param message message of the log event
+     * @param data structured data associated with the log event
+     *
+     */
+    protected static _log(level:OINOLogLevel, levelStr:string, message:string, data?:any):void {
+        // console.log("_log: level=" + level + ", levelStr=" + levelStr + ", message=" + message + ", data=" + data)
+        if ((OINOLog._instance) && (OINOLog._instance._logLevel <= level)) {
+            OINOLog._instance?._writeLog(levelStr, message, data)
+        }
+    }
+
+    /**
+     * Set active logger and log level.
+     * 
+     * @param logger logger instance
+     *
+     */
+    static setLogger(logger: OINOLog) {
+        // console.log("setLogger: " + log)
+        if (logger) {
+            OINOLog._instance = logger
+        }
+    }
+
+    /**
+     * Set log level.
+     *
+     * @param logLevel log level to use
+     * 
+     */
+    static setLogLevel(logLevel:OINOLogLevel) {
+        if (OINOLog._instance) {
+            OINOLog._instance._logLevel = logLevel
+        }
+    }
+
+    /**
+     * Log error event.
+     * 
+     * @param message message of the log event
+     * @param data structured data associated with the log event
+     *
+     */
+    static error(message:string, data?:any) {
+        OINOLog._log(OINOLogLevel.error, "ERROR", message, data)
+    }
+
+    /**
+     * Log warning event.
+     * 
+     * @param message message of the log event
+     * @param data structured data associated with the log event
+     *
+     */
+    static warning(message:string, data?:any) {
+        OINOLog._log(OINOLogLevel.warn, "WARN", message, data)
+    }
+
+    /**
+     * Log info event.
+     * 
+     * @param message message of the log event
+     * @param data structured data associated with the log event
+     *
+     */
+    static info(message:string, data?:any) {
+        OINOLog._log(OINOLogLevel.info, "INFO", message, data)
+    }
+
+    /**
+     * Log debug event.
+     * 
+     * @param message message of the log event
+     * @param data structured data associated with the log event
+     *
+     */
+    static debug(message:string, data?:any) {
+        OINOLog._log(OINOLogLevel.debug, "DEBUG", message, data)
+    }
+}
+
+/**
+ * Logging implementation based on console.log.
+ *
+ */
+export class OINOConsoleLog extends OINOLog {
+
+    /**
+     * Constructor of `OINOConsoleLog`
+     * @param logLevel logging level
+     */
+    constructor (logLevel:OINOLogLevel = OINOLogLevel.warn) {
+        super(logLevel)
+    }
+
+    protected _writeLog(level:string, message:string, data?:any):void {
+        let log:string = "OINOLog " + level + ": " + message
+        if (data) {
+            log += " " + JSON.stringify(data)
+        }
+        console.log(log)
+    }
+}

package/src/OINOResult.ts

@@ -0,0 +1,143 @@
+/*
+ * 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 { OINO_DEBUG_PREFIX, OINO_ERROR_PREFIX, OINO_INFO_PREFIX, OINO_WARNING_PREFIX } from ".";
+
+/**
+ * OINO API request result object with returned data and/or http status code/message and 
+ * error / warning messages.
+ *
+ */
+export class OINOResult {
+    /** Wheter request was successfully executed */
+    success: boolean
+
+    /** HTTP status code */
+    statusCode: number;
+
+    /** HTTP status message */
+    statusMessage: string;
+
+    /** Error / warning messages */
+    messages: string[];
+
+    /**
+     * Constructor of OINOResult.
+     * 
+     */
+    constructor () {
+        this.success = true
+        this.statusCode = 200
+        this.statusMessage = "OK"
+        this.messages = []
+    }
+
+    /**
+     * Set HTTP OK status (does not reset messages).
+     *
+     */
+    setOk() {
+        this.success = true
+        this.statusCode = 200
+        this.statusMessage = "OK"
+    }
+
+    /**
+     * Set HTTP error status using given code and message.
+     * 
+     * @param statusCode HTTP status code
+     * @param statusMessage HTTP status message
+     * @param operation operation where error occured
+     *
+     */
+    setError(statusCode:number, statusMessage:string, operation:string) {
+        this.success = false
+        this.statusCode = statusCode
+        if (this.statusMessage != "OK") {
+            this.messages.push(this.statusMessage) // latest error becomes status, but if there was something non-trivial, add it to the messages
+        }
+        if (statusMessage.startsWith(OINO_ERROR_PREFIX)) {
+            this.statusMessage = statusMessage
+        } else {
+            this.statusMessage = OINO_ERROR_PREFIX + " (" + operation + "): " + statusMessage
+        }
+    }
+
+    /**
+     * Add warning message.
+     *
+     * @param message HTTP status message
+     * @param operation operation where warning occured
+     * 
+     */
+    addWarning(message:string, operation:string) {
+        message = message.trim()
+        if (message) {
+            this.messages.push(OINO_WARNING_PREFIX + " (" + operation + "): " + message)
+        }
+    }
+
+    /**
+     * Add info message.
+     *
+     * @param message HTTP status message
+     * @param operation operation where info occured
+     *
+     */
+    addInfo(message:string, operation:string) {
+        message = message.trim()
+        if (message) {
+            this.messages.push(OINO_INFO_PREFIX + " (" + operation + "): " + message)
+        }
+    }
+
+    /**
+     * Add debug message.
+     *
+     * @param message HTTP status message
+     * @param operation operation where debug occured
+     *
+     */
+    addDebug(message:string, operation:string) {
+        message = message.trim()
+        if (message) {
+            this.messages.push(OINO_DEBUG_PREFIX + " (" + operation + "): " + message)
+        }
+    }
+
+    /**
+     * Copy given messages to HTTP headers.
+     *
+     * @param headers HTTP headers
+     * @param copyErrors wether error messages should be copied (default true)
+     * @param copyWarnings wether warning messages should be copied (default false)
+     * @param copyInfos wether info messages should be copied (default false)
+     * @param copyDebug wether debug messages should be copied (default false)
+     *
+     */
+    copyMessagesToHeaders(headers:Headers, copyErrors:boolean = true, copyWarnings:boolean = false, copyInfos:boolean = false, copyDebug:boolean = false) {
+        let j=1
+        for(let i=0; i<this.messages.length; i++) {
+            const message = this.messages[i].replaceAll("\r", " ").replaceAll("\n", " ")
+            if (copyErrors && message.startsWith(OINO_ERROR_PREFIX)) {
+                headers.append('X-OINO-MESSAGE-'+j, message)
+                j++
+            } 
+            if (copyWarnings && message.startsWith(OINO_WARNING_PREFIX)) {
+                headers.append('X-OINO-MESSAGE-'+j, message)
+                j++
+            } 
+            if (copyInfos && message.startsWith(OINO_INFO_PREFIX)) {
+                headers.append('X-OINO-MESSAGE-'+j, message)
+                j++
+            } 
+            if (copyDebug && message.startsWith(OINO_DEBUG_PREFIX)) {
+                headers.append('X-OINO-MESSAGE-'+j, message)
+                j++
+            } 
+        }
+    }
+}

package/src/OINOStr.ts

@@ -0,0 +1,254 @@
+import { OINOContentType } from "."
+
+/** Callback to filter data fields */
+export type OINOStrEncoder = (str:string) => string
+
+/**
+ * Static class string utilities.
+ *
+ */
+export class OINOStr {
+
+    /**
+     * Split string by the top level of the given type of brackets.
+     * E.g. splitByBrackets("a(bc(d))ef(gh)kl", true, true, '(', ')') would return ["a", "bc(d)", "ef", "gh", "kl"]
+     * 
+     * @param str string to split
+     * @param includePartsBetweenBlocks whether to include strings between top level brackets
+     * @param includeTrailingUnescapedBlock whether to include final block that is missing necessary end brackets
+     * @param startBracket starting bracket, e.g. '('
+     * @param endBracket ending bracket, e.g. ')'
+     *
+     */
+    static splitByBrackets(str:string, includePartsBetweenBlocks:boolean, includeTrailingUnescapedBlock:boolean, startBracket:string, endBracket:string):string[] {
+
+        let result:string[] = []
+        let parenthesis_count:number = 0
+        let start:number = 0
+        let end:number = 0
+        while (end<str.length) {
+            if (str[end] == startBracket) {
+                if (parenthesis_count == 0) {
+                    if ((end > start) && includePartsBetweenBlocks) { // there is some first level string to add to result
+                        result.push(str.substring(start, end))
+                    }
+                    start = end+1 
+                }
+                parenthesis_count++
+
+            } else if (str[end] == endBracket) {
+                parenthesis_count--
+                if (parenthesis_count == 0) {
+                    if (end >= start) { 
+                        result.push(str.substring(start, end))
+                    }
+                    start = end+1 
+                }
+            }
+            end++
+        }
+        if ((end > start) && ((includePartsBetweenBlocks && (parenthesis_count == 0)) || (includeTrailingUnescapedBlock && (parenthesis_count > 0)))) { // if there is stuff after last block or unfinished block (and those are supported)
+            result.push(str.substring(start, end)) // i == str.length
+        }
+        return result
+    }
+
+    /**
+     * Split string by delimeter excluding delimeters inside given brackets.
+     * E.g. splitExcludingBrackets("a,(bc,d),ef,(g,h),k", ',', '(', ')') would return ["a", "bc,d", "ef", "g,h", "k"]
+     * 
+     * @param str string to split
+     * @param delimeter string to use as delimeter
+     * @param startBracket starting bracket, e.g. '('
+     * @param endBracket ending bracket, e.g. ')'
+     */
+    static splitExcludingBrackets(str:string, delimeter:string, startBracket:string, endBracket:string):string[] {
+        let result:string[] = []
+        let bracket_level:number = 0
+        let start:number = 0
+        let end:number = 0
+        while (end<str.length) {
+            if (str[end] == startBracket) {
+                bracket_level++
+            } else if (str[end] == endBracket) {
+                bracket_level--
+            } else if ((str[end] == delimeter) && (bracket_level==0)) { // only delimeters at top level will break 
+                result.push(str.substring(start, end))
+                start = end+1
+            }
+            end++
+        }
+        if (end > start) {
+            result.push(str.substring(start, end)) // i == str.length
+        }
+        return result
+    }
+
+    /**
+     * Encode OINO serialized strings as valid JSON.
+     * 
+     * @param str string to encode
+     * @param valueType wether it is a value type
+     */
+    static encodeJSON(str:string|null|undefined, valueType:boolean = false):string {
+        if (str === undefined) { // no undefined literal in JSON
+            return "null"
+        } else if (str === null) {
+            return "null"
+        } else {
+            if (valueType) {
+                return str
+            } else {
+                return JSON.stringify(str)
+            }       
+        } 
+    }
+
+    /**
+     * Decode JSON string as OINO serialization.
+     * 
+     * @param str string to decode
+     */
+    static decodeJSON(str:string):string|null|undefined {
+        return str // JSON parsing using JS methods, no need to decode anything
+    }
+
+    /**
+     * Encode OINO serialized strings as valid CSV.
+     * 
+     * @param str string to encode
+     */
+    static encodeCSV(str:string|null|undefined):string {
+        if (str === undefined) { 
+            return ""
+        } else if (str === null) {
+            return "null"
+        } else {
+            return "\"" + str.replaceAll("\"", "\"\"") + "\"";
+        }
+    }
+
+    /**
+     * Decode CSV string as OINO serialization.
+     * 
+     * @param str string to decode
+     */
+    static decodeCSV(str:string):string|null|undefined {
+        return str.replaceAll("\"\"", "\"")
+    }
+    
+    /**
+     * Encode OINO serialized strings as valid Formdata.
+     * 
+     * @param str string to encode
+     */
+    static encodeFormdata(str:string|null|undefined):string {
+        if (str === undefined) { 
+            return ""
+        } else if (str === null) {
+            return ""
+        } else {
+            return str
+        }
+    }
+
+    /**
+     * Decode Formdata string as OINO serialization.
+     * 
+     * @param str string to decode
+     */
+    static decodeFormdata(str:string):string|null|undefined {
+        return str
+    }
+    /**
+     * Encode OINO serialized strings as valid Urlencode.
+     * 
+     * @param str string to encode
+     */
+    static encodeUrlencode(str:string|null|undefined):string {
+        if (str === undefined) { 
+            return ""
+        } else if (str === null) {
+            return "null"
+        } else {
+            return encodeURIComponent(str)
+        }
+    }
+
+    /**
+     * Decode Urlencode string as OINO serialization.
+     * 
+     * @param str string to decode
+     */
+    static decodeUrlencode(str:string):string|null|undefined {
+        return decodeURIComponent(str)
+    }
+
+    /**
+     * Encode OINO serialized strings as valid HTML content.
+     * 
+     * @param str string to encode
+     */
+    static encodeHtml(str:string|null|undefined):string {
+        if (str === undefined) { 
+            return ""
+        } else if (str === null) {
+            return ""
+        } else {
+            return str.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&#039;')
+        }
+    }
+
+    /**
+     * Decode HTML string as OINO serialization.
+     * 
+     * @param str string to encode
+     */
+    static decodeHtml(str:string):string|null|undefined {
+        return str.replaceAll('&amp;', '&').replaceAll('&lt;', '<').replaceAll('&gt;', '>').replaceAll('&quot;', '"').replaceAll('&#039;', "'")
+    }
+    /**
+     * Decode content type formatted string as OINO serialization.
+     * 
+     * @param str string to decode
+     * @param contentType content type for serialization
+     * 
+     */
+    static decode(str:string, contentType:OINOContentType):string|null|undefined {
+        if (contentType == OINOContentType.csv) {
+            return this.decodeCSV(str)
+        } else if (contentType == OINOContentType.json) {
+            return this.decodeJSON(str)
+        } else if (contentType == OINOContentType.formdata) {
+            return this.decodeFormdata(str)
+        } else if (contentType == OINOContentType.urlencode) {
+            return this.decodeUrlencode(str)
+        } else if (contentType == OINOContentType.html) {
+            return str 
+        } else {
+            return str
+        }
+    }
+    /**
+     * Encode OINO serialized string to the content type formatting.
+     * 
+     * @param str string to encode
+     * @param contentType content type for serialization
+     * 
+     */
+    static encode(str:string|null|undefined, contentType:OINOContentType):string {
+        if (contentType == OINOContentType.csv) {
+            return this.encodeCSV(str)
+        } else if (contentType == OINOContentType.json) {
+            return this.encodeJSON(str)
+        } else if (contentType == OINOContentType.formdata) {
+            return this.encodeFormdata(str)
+        } else if (contentType == OINOContentType.urlencode) {
+            return this.encodeUrlencode(str)
+        } else if (contentType == OINOContentType.html) {
+            return this.encodeHtml(str)
+        } else {
+            return str || ""
+        }
+    }
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+export { OINOBenchmark } from "./OINOBenchmark.js"
+export { OINOLog, OINOLogLevel, OINOConsoleLog } from "./OINOLog.js"
+export { OINOResult } from "./OINOResult.js"
+export { OINOStr } from "./OINOStr.js"
+
+/** 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"
+
+/** 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' 
+}
+