@oino-ts/common 0.21.2 → 1.0.0

package/src/OINODataModel.ts

@@ -0,0 +1,187 @@
+/*
+ * 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 { OINODataRow } from "./OINOConstants.js"
+import { OINOApi } from "./OINOApi.js"
+import { OINODataField, OINONumberDataField, OINODataFieldFilter } from "./OINODataField.js"
+
+/**
+ * OINO Datamodel object for representing one database table and it's columns.
+ *
+ */
+export class OINODataModel {
+    private _fieldIndexLookup:Record<string, number>;
+
+    /** Database refererence of the table */
+    readonly api:OINOApi 
+
+    /** Field refererences of the API */
+    readonly fields: OINODataField[]
+
+    /**
+     * 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:OINOApi) {
+        this._fieldIndexLookup = {}
+        this.api = api
+        this.fields = []
+    }
+
+    /**
+     * Add a field to the datamodel.
+     * 
+     * @param field dataset field
+     *
+     */
+    addField(field:OINODataField) {
+        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:string):OINODataField|null {
+        const i:number = 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:string):number {
+        const i:number = 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:OINODataFieldFilter):OINODataField[] {
+        let result:OINODataField[] = []
+        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: OINODataRow, hashidValues:boolean = false): string[] {
+        let values: string[] = [];
+        for (let i=0; i< this.fields.length; i++) {
+            const f = this.fields[i]
+            if (f.fieldParams.isPrimaryKey) {
+                const value:string = 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: OINODataField, length:number = 0): string {
+        let params: string = "";
+        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:number = length - 2 - 1 - params.length
+        let result:string = 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:string = ""): string {
+        let result: string = 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():string {
+        const result:string = JSON.stringify(this.fields, (key:any, value:any) => { 
+            if (key.startsWith("_")) {
+                return undefined
+            } else {
+                return value
+            }
+        })
+        return result
+    }
+}

package/src/OINODataSource.ts

@@ -0,0 +1,280 @@
+import { OINODataCell, OINODataRow, OINO_EMPTY_ROW, OINO_ERROR_PREFIX } from "./OINOConstants.js"
+import { OINOResult } from "./OINOResult.js"
+import { OINOApi } from "./OINOApi.js"
+
+/**
+ * Base class for database abstraction, implementing methods for connecting, making queries and parsing/formatting data 
+ * between SQL and serialization formats.
+ *
+ */
+export abstract class OINODataSource {
+
+    isConnected:boolean = false
+    isValidated:boolean = false
+
+    /**
+     * Connect to database.
+     *
+     */
+    abstract connect(): Promise<OINOResult>
+    
+    /**
+     * Validate connection to database is working. 
+     *
+     */
+    abstract validate(): Promise<OINOResult>
+    
+    /**
+     * Disconnect from database.
+     *
+     */
+    abstract disconnect(): Promise<void>    
+
+    /**
+     * Print a table name using database specific SQL escaping.
+     * 
+     * @param sqlTable name of the table
+     *
+     */
+    abstract printTableName(sqlTable:string): string
+
+    /**
+     * Print a column name with correct SQL escaping.
+     * 
+     * @param sqlColumn name of the column
+     *
+     */
+    abstract printColumnName(sqlColumn:string): string
+
+    /**
+     * Print a single data value from serialization using the context of the native data
+     * type with the correct SQL escaping.
+     * 
+     * @param cellValue data from sql results
+     * @param sqlType native type name for table column
+     *
+     */
+    abstract printCellAsValue(cellValue:OINODataCell, sqlType: string): string
+
+    /**
+     * Print a single string value as valid sql literal
+     * 
+     * @param sqlString string value
+     *
+     */
+    abstract printStringValue(sqlString:string): string
+
+    /**
+     * Parse a single SQL result value for serialization using the context of the native data
+     * type.
+     * 
+     * @param sqlValue data from serialization
+     * @param sqlType native type name for table column
+     * 
+     */
+    abstract parseValueAsCell(sqlValue:OINODataCell, sqlType: string): OINODataCell
+    
+    /**
+     * Initialize a data model by getting the SQL schema and populating OINODataFields of 
+     * the model.
+     * 
+     * @param api api which data model to initialize.
+     *
+     */
+    abstract initializeApiDatamodel(api:OINOApi): Promise<void>
+
+}
+
+/**
+ * Base class for SQL results that can be asynchronously iterated (but
+ * not necessarity rewinded). Idea is to handle database specific mechanisms
+ * for returning and formatting conventions in the database specific
+ * implementation. Data might be in memory or streamed in chunks and
+ * `OINODataSet` will serve it out consistently.
+ *
+ */
+
+export abstract class OINODataSet extends OINOResult {
+    private _data: unknown;
+
+    /** Error messages */
+    readonly messages: string[]
+
+    /**
+     * Constructor for `OINODataSet`.
+     *
+     * @param data internal database specific data type (constructor will throw if invalid)
+     * @param messages error messages from SQL-query
+     *
+     */
+    constructor(data: unknown, messages: string[] = []) {
+        super();
+        this._data = data;
+        this.messages = messages;
+    }
+
+
+    /**
+     * Is data set empty.
+     *
+     */
+    abstract isEmpty(): boolean;
+
+    /**
+     * Is there no more content, i.e. either dataset is empty or we have moved beyond last line
+     *
+     */
+    abstract isEof(): boolean;
+
+    /**
+     * Attempts to moves dataset to the next row, possibly waiting for more data to become available. Returns !isEof().
+     *
+     */
+    abstract next(): Promise<boolean>;
+
+    /**
+     * Gets current row of data.
+     *
+     */
+    abstract getRow(): OINODataRow;
+
+    /**
+     * Gets all rows of data. 
+     * 
+     * NOTE: This is left abstract instead of just using `getRow()` so that DB implementations can hopefully optimize not duplicating data     *
+     */
+    abstract getAllRows(): Promise<OINODataRow[]>;
+
+    /**
+     * Checks if the messages contain errors.
+     *
+     */
+    hasErrors(): boolean {
+        for (let i = 0; i < this.messages.length; i++) {
+            if (this.messages[i].startsWith(OINO_ERROR_PREFIX)) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Finds the first error message that occured
+     *
+     */
+    getFirstError(): string {
+        for (let i = this.messages.length-1; i >= 0; i--) {
+            if (this.messages[i].startsWith(OINO_ERROR_PREFIX)) {
+                return this.messages[i];
+            }
+        }
+        return "";
+    }
+
+    /**
+     * Finds the last error message that occured
+     *
+     */
+    getLastError(): string {
+        for (let i = 0; i < this.messages.length; i++) {
+            if (this.messages[i].startsWith(OINO_ERROR_PREFIX)) {
+                return this.messages[i];
+            }
+        }
+        return "";
+    }
+}
+
+/**
+ * Generic in memory implementation of a data set where data is an array of rows. Used
+ * by BunSqlite and automated testing. Can be rewinded.
+ *
+ */
+
+export class OINOMemoryDataset extends OINODataSet {
+    private _rows: OINODataRow[];
+    private _currentRow: number;
+    private _eof: boolean;
+
+    /**
+     * Constructor of `OINOMemoryDataset`.
+     *
+     * @param data data as OINODataRow[] (constructor will throw if invalid)
+     * @param errors error messages from SQL-query
+     *
+     */
+    constructor(data: unknown, errors: string[] = []) {
+        super(data, errors);
+        if ((data == null) || !(Array.isArray(data))) {
+            throw new Error(OINO_ERROR_PREFIX + ": Data needs to be compatible with OINORow[]!"); // TODO: maybe check all rows
+        }
+        this._rows = data as OINODataRow[];
+        if (this.isEmpty()) {
+            this._currentRow = -1;
+            this._eof = true;
+        } else {
+            this._currentRow = 0;
+            this._eof = false;
+        }
+    }
+
+    /**
+     * Is data set empty.
+     *
+     */
+    isEmpty(): boolean {
+        return (this._rows.length == 0);
+    }
+
+    /**
+     * Is there no more content, i.e. either dataset is empty or we have moved beyond last line
+     *
+     */
+    isEof(): boolean {
+        return (this._eof);
+    }
+
+    /**
+     * Attempts to moves dataset to the next row, possibly waiting for more data to become available. Returns !isEof().
+     *
+     */
+    async next(): Promise<boolean> {
+        if (this._currentRow < this._rows.length - 1) {
+            this._currentRow = this._currentRow + 1;
+        } else {
+            this._eof = true;
+        }
+        return Promise.resolve(!this._eof);
+    }
+
+    /**
+     * Gets current row of data.
+     *
+     */
+    getRow(): OINODataRow {
+        if ((this._currentRow >= 0) && (this._currentRow < this._rows.length)) {
+            return this._rows[this._currentRow];
+        } else {
+            return OINO_EMPTY_ROW;
+        }
+    }
+
+    /**
+     * Gets all rows of data.
+     *
+     */
+    async getAllRows(): Promise<OINODataRow[]> {
+        return this._rows // at the moment theres no result streaming, so we can just return the rows
+    }
+
+    /**
+     * Rewinds data set to the first row, returns !isEof().
+     *
+     */
+    first(): boolean {
+        this._currentRow = 0;
+        this._eof = this._rows.length == 0;
+        return !this._eof;
+    }
+}
+