@oino-ts/common 0.1.0

package/src/OINOHtmlTemplate.ts

@@ -0,0 +1,186 @@
+import { OINOStr, OINOContentType, OINOResult, OINOHttpResult, OINO_ERROR_PREFIX, OINO_WARNING_PREFIX, OINO_INFO_PREFIX, OINO_DEBUG_PREFIX, OINOBenchmark } from "."
+
+/**
+ * Class for rendering HTML from data. 
+ */
+export class OINOHtmlTemplate {
+    private _tag:string
+    private _tagCleanRegex:RegExp 
+    private _variables:Record<string, string> = {}
+    /** HTML template string */
+	template: string;
+
+    /** Cache modified value for template */
+	modified: number;
+
+    /** Cache expiration value for template */
+	expires: number;
+
+    /**
+     * Creates HTML Response from a key-value-pair.
+     *
+     * @param template template string
+     * @param tag tag to identify variables in template
+     * 
+     */
+	constructor (template:string, tag:string = "###") {
+		this.template = template
+		this.modified = 0
+		this.expires = 0
+        this._tag = tag
+        this._tagCleanRegex = new RegExp(tag + ".*" + tag, "g")
+	}
+
+    /**
+     * @returns whether template is empty
+     */
+	isEmpty():boolean {
+		return this.template == ""
+	}
+
+    protected _createHttpResult(html:string, removeUnusedTags:boolean):OINOHttpResult {
+        if (removeUnusedTags) {
+            html = html.replace(this._tagCleanRegex, "")
+        }
+        const result:OINOHttpResult = new OINOHttpResult(html)
+        if (this.expires >= 1) {
+            result.expires = Math.round(this.expires)
+        }
+        if (this.modified >= 1) {
+            result.lastModified = this.modified
+        }
+        return result
+    }
+
+    protected _renderHtml():string {
+        let html:string = this.template
+        for (let key in this._variables) {
+            const value = this._variables[key]
+            html = html.replaceAll(this._tag + key + this._tag, value)
+        }
+        return html
+    }
+
+    /**
+     * Clear template variables.
+     *
+     */
+    clearVariables() {
+        this._variables = {}
+    }
+
+    /**
+     * Sets template variable from a key-value-pair.
+     *
+     * @param variable key
+     * @param value value
+     * @param escapeValue whether to escape value
+     * 
+     */
+    setVariableFromValue(variable:string, value:string, escapeValue:boolean = true) {
+        if (escapeValue) {
+            value = OINOStr.encode(value, OINOContentType.html)
+        }
+        this._variables[variable] = value
+    }
+
+    /**
+     * Sets template variables from object properties.
+     *
+     * @param object any object
+     * @param escapeValue whether to escape value
+     * 
+     */
+    setVariableFromProperties(object:any, escapeValue:boolean = true) {
+        if (object) {
+            for (let key in object) {
+                if (escapeValue) {
+                    this._variables[key] = OINOStr.encode(object[key], OINOContentType.html)
+                } else {
+                    this._variables[key] = object[key]
+                }
+            }
+        }
+    }
+
+    /**
+     * Creates HTML Response from set variables.
+     *
+     * @param removeUnusedTags whether to remove unused tags
+     * 
+     */
+    render(removeUnusedTags:boolean = true):OINOHttpResult {
+        return this._createHttpResult(this._renderHtml(), removeUnusedTags)
+    }
+
+    /**
+     * Creates HTML Response from a key-value-pair.
+     *
+     * @param key key
+     * @param value value
+     * @param removeUnusedTags whether to remove unused tags
+     * 
+     */
+    renderFromKeyValue(key:string, value:string, removeUnusedTags:boolean = true):OINOHttpResult {
+        OINOBenchmark.start("OINOHtmlTemplate", "renderFromKeyValue")
+        this.setVariableFromValue(key, value)
+        const result:OINOHttpResult = this.render(removeUnusedTags)
+        OINOBenchmark.end("OINOHtmlTemplate", "renderFromKeyValue")
+        return result
+    }
+
+	/**
+     * Creates HTML Response from object properties.
+     *
+     * @param object object
+     * @param removeUnusedTags whether to remove unused tags
+     * 
+     */
+    renderFromObject(object:any, removeUnusedTags:boolean = true):OINOHttpResult {
+        OINOBenchmark.start("OINOHtmlTemplate", "renderFromObject")
+        this.setVariableFromProperties(object)
+        const result:OINOHttpResult = this.render(removeUnusedTags)
+        OINOBenchmark.end("OINOHtmlTemplate", "renderFromObject")
+        return result
+    }
+
+    /**
+     * Creates HTML Response from API result.
+     *
+     * @param result OINOResult-object
+     * @param removeUnusedTags whether to remove unused tags
+     * @param messageSeparator HTML separator for messages
+     * @param includeErrorMessages include debug messages in result
+     * @param includeWarningMessages include debug messages in result
+     * @param includeInfoMessages include debug messages in result
+     * @param includeDebugMessages include debug messages in result
+     * 
+     */
+    renderFromResult(result:OINOResult, removeUnusedTags:boolean=true, messageSeparator:string, includeErrorMessages:boolean=false, includeWarningMessages:boolean=false, includeInfoMessages:boolean=false, includeDebugMessages:boolean=false):OINOHttpResult {
+        OINOBenchmark.start("OINOHtmlTemplate", "renderFromResult")
+        this.setVariableFromValue("statusCode", result.statusCode.toString())
+        this.setVariableFromValue("statusMessage", result.statusMessage.toString())
+        let messages:string[] = []
+        for (let i:number = 0; i<result.messages.length; i++) {
+            if (includeErrorMessages && result.messages[i].startsWith(OINO_ERROR_PREFIX)) {
+                messages.push(OINOStr.encode(result.messages[i], OINOContentType.html))
+            } 
+            if (includeWarningMessages && result.messages[i].startsWith(OINO_WARNING_PREFIX)) {
+                messages.push(OINOStr.encode(result.messages[i], OINOContentType.html))
+            } 
+            if (includeInfoMessages && result.messages[i].startsWith(OINO_INFO_PREFIX)) {
+                messages.push(OINOStr.encode(result.messages[i], OINOContentType.html))
+            } 
+            if (includeDebugMessages && result.messages[i].startsWith(OINO_DEBUG_PREFIX)) {
+                messages.push(OINOStr.encode(result.messages[i], OINOContentType.html))
+            } 
+            
+        }
+        if (messages.length > 0) {
+            this.setVariableFromValue("messages", messages.join(messageSeparator), false) // messages have been escaped already
+        }        
+        const http_result:OINOHttpResult = this.render(removeUnusedTags)
+        OINOBenchmark.end("OINOHtmlTemplate", "renderFromResult")
+        return http_result
+    }
+};

package/src/OINOLog.ts

@@ -0,0 +1,168 @@
+/*
+ * 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)
+        }
+        if (level == "ERROR") {
+            console.error(log)
+        } else if (level == "WARN") {
+            console.warn(log)
+        } else if (level == "INFO") {
+            console.info(log)
+        } else {
+            console.log(log)
+        }
+    }
+}

package/src/OINOResult.ts

@@ -0,0 +1,234 @@
+/*
+ * 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 { createHash, Hash } from "node:crypto";
+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 = []
+    }
+
+    /**
+     * Copy values from different result.
+     * 
+     * @param result source value
+     */
+    copy(result: OINOResult) {
+        this.success = result.success
+        this.statusCode = result.statusCode
+        this.statusMessage = result.statusMessage
+        this.messages = result.messages.slice()
+    }
+
+    /**
+     * 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. Returns self reference for chaining.
+     * 
+     * @param statusCode HTTP status code
+     * @param statusMessage HTTP status message
+     * @param operation operation where error occured
+     *
+     */
+    setError(statusCode:number, statusMessage:string, operation:string):OINOResult {
+        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
+        }
+        return this
+    }
+
+    /**
+     * Add warning message. Returns self reference for chaining.
+     *
+     * @param message HTTP status message
+     * @param operation operation where warning occured
+     * 
+     */
+    addWarning(message:string, operation:string):OINOResult {
+        message = message.trim()
+        if (message) {
+            this.messages.push(OINO_WARNING_PREFIX + " (" + operation + "): " + message)
+        }
+        return this
+    }
+
+    /**
+     * Add info message. Returns self reference for chaining.
+     *
+     * @param message HTTP status message
+     * @param operation operation where info occured
+     *
+     */
+    addInfo(message:string, operation:string):OINOResult {
+        message = message.trim()
+        if (message) {
+            this.messages.push(OINO_INFO_PREFIX + " (" + operation + "): " + message)
+        }
+        return this
+    }
+
+    /**
+     * Add debug message. Returns self reference for chaining.
+     *
+     * @param message HTTP status message
+     * @param operation operation where debug occured
+     *
+     */
+    addDebug(message:string, operation:string):OINOResult {
+        message = message.trim()
+        if (message) {
+            this.messages.push(OINO_DEBUG_PREFIX + " (" + operation + "): " + message)
+        }
+        return this
+    }
+
+    /**
+     * 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++
+            } 
+        }
+    }
+
+    /**
+     * Print result for logging.
+     * 
+     */
+    printLog() {
+        return "OINOResult: statusCode=" + this.statusCode + ", statusMessage=" + this.statusMessage + ", messages=[" + this.messages.join(", ") + "]"
+    }
+}
+
+/**
+ * Specialized result for HTTP responses.
+ */
+export class OINOHttpResult extends OINOResult {
+    private _etag:string
+
+    /** HTTP body data */
+    readonly body: string
+
+    /** HTTP cache expiration value */
+    expires: number
+
+    /** HTTP cache last-modified value */
+    lastModified: number
+
+    /**
+     * Constructor for a `OINOHttpResult` 
+     * 
+     * @param body HTTP body
+     * 
+     */
+    constructor(body:string) {
+        super()
+        this.body = body
+        this.expires = 0
+        this.lastModified = 0
+        this._etag = ""
+    }
+
+    /**
+     * Get the ETag value for the body opportunistically, i.e. don't calculate until requested and reuse value.
+     * 
+     */
+    getEtag():string {
+        if (this._etag == "") {
+            const hash:Hash = createHash("sha256")
+            this._etag = hash.update(this.body).digest("hex")
+        }
+        return this._etag
+    }
+
+    /**
+     * Get a Response object from the result values.
+     * 
+     * @param headers HTTP headers (overrides existing values)
+     */
+    getResponse(headers?:Record<string, string>):Response {
+        const result:Response = new Response(this.body, {status:this.statusCode, statusText: this.statusMessage, headers: headers})
+        result.headers.set('Content-Length', this.body.length.toString())
+        if (this.lastModified > 0) {
+            result.headers.set('Last-Modified', new Date(this.lastModified).toUTCString())
+        }
+        if (this.expires >= 0) {
+            result.headers.set('Expires', Math.round(this.expires).toString())
+            if (this.expires == 0) {
+                result.headers.set('Pragma', 'no-cache')
+            }
+        }
+        result.headers.set("ETag", this.getEtag())
+        return result
+    }
+
+
+
+}