@oino-ts/db 0.21.2 → 1.0.1

package/src/OINODbFactory.ts

@@ -1,69 +1,74 @@
-/*
- * 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 { OINODbApi, OINODbApiParams, OINODbParams, OINODb, OINODbConstructor } from "./index.js"
-
-/**
- * Static factory class for easily creating things based on data
- *
- */
-export class OINODbFactory {
-    private static _dbRegistry:Record<string, OINODbConstructor> = {}
-
-    /**
-     * Register a supported database class. Used to enable those that are installed in the factory 
-     * instead of forcing everyone to install all database libraries.
-     *
-     * @param dbName name of the database implementation class
-     * @param dbTypeClass constructor for creating a database of that type
-     */
-    static registerDb(dbName:string, dbTypeClass: OINODbConstructor):void {
-        this._dbRegistry[dbName] = dbTypeClass
-    }
-
-    /**
-     * Create database from parameters from the registered classes.
-     * 
-     * @param params database connection parameters
-     * @param connect if true, connects to the database
-     * @param validate if true, validates the database connection
-     */
-    static async createDb(params:OINODbParams, connect:boolean = true, validate:boolean = true):Promise<OINODb> {
-        let result:OINODb
-        let db_type = this._dbRegistry[params.type]
-        if (db_type) {
-            result = new db_type(params)
-        } else {
-            throw new Error("Unsupported database type: " + params.type)
-        }
-        if (connect) {
-            const connect_res = await result.connect()
-            if (connect_res.success == false) {
-                throw new Error("Database connection failed: " + connect_res.statusText)
-            }
-        }
-        if (validate) {
-            const validate_res = await result.validate()
-            if (validate_res.success == false) {
-                throw new Error("Database validation failed: " + validate_res.statusText)
-            }
-        }
-        return result
-    }
-
-
-    /**
-     * Create API from parameters and calls initDatamodel on the datamodel.
-     * 
-     * @param db databased used in API
-     * @param params parameters of the API
-     */
-    static async createApi(db: OINODb, params: OINODbApiParams):Promise<OINODbApi> {
-        let result:OINODbApi = new OINODbApi(db, params)
-        await db.initializeApiDatamodel(result)
-        return result
-    }
+/*
+ * 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 { OINOApiParams } from "@oino-ts/common"
+
+import { OINODbParams, OINODbConstructor } from "./OINODbConstants.js"
+import { OINODbApi } from "./OINODbApi.js"
+import { OINODb } from "./OINODb.js"
+import { OINODbDataModel } from "./OINODbDataModel.js"
+
+/**
+ * Static factory class for easily creating things based on data
+ *
+ */
+export class OINODbFactory {
+    private static _dbRegistry:Record<string, OINODbConstructor> = {}
+
+    /**
+     * Register a supported database class. Used to enable those that are installed in the factory 
+     * instead of forcing everyone to install all database libraries.
+     *
+     * @param dbName name of the database implementation class
+     * @param dbTypeClass constructor for creating a database of that type
+     */
+    static registerDb(dbName:string, dbTypeClass: OINODbConstructor):void {
+        this._dbRegistry[dbName] = dbTypeClass
+    }
+
+    /**
+     * Create database from parameters from the registered classes.
+     * 
+     * @param params database connection parameters
+     * @param connect if true, connects to the database
+     * @param validate if true, validates the database connection
+     */
+    static async createDb(params:OINODbParams, connect:boolean = true, validate:boolean = true):Promise<OINODb> {
+        let result:OINODb
+        let db_type = this._dbRegistry[params.type]
+        if (db_type) {
+            result = new db_type(params)
+        } else {
+            throw new Error("Unsupported database type: " + params.type)
+        }
+        if (connect) {
+            const connect_res = await result.connect()
+            if (connect_res.success == false) {
+                throw new Error("Database connection failed: " + connect_res.statusText)
+            }
+        }
+        if (validate) {
+            const validate_res = await result.validate()
+            if (validate_res.success == false) {
+                throw new Error("Database validation failed: " + validate_res.statusText)
+            }
+        }
+        return result
+    }
+
+
+    /**
+     * Create API from parameters and calls initDatamodel on the datamodel.
+     * 
+     * @param db databased used in API
+     * @param params parameters of the API
+     */
+    static async createApi(db: OINODb, params: OINOApiParams):Promise<OINODbApi> {
+        let result:OINODbApi = new OINODbApi(db, params)
+        await db.initializeApiDatamodel(result)
+        return result
+    }
 }

package/src/OINODbQueryParams.ts

@@ -0,0 +1,203 @@
+/*
+ * 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_ERROR_PREFIX, OINOLog, OINODataField, OINOQueryNullCheck, OINOQueryFilter, OINOQueryOrder, OINOQueryLimit, OINOQueryAggregate, OINOQueryAggregateFunctions, OINOQuerySelect, OINODataModel } from "@oino-ts/common"
+
+import { OINODbDataModel } from "./OINODbDataModel.js"
+
+/**
+ * Class for recursively parsing of filters and printing them as SQL conditions. 
+ * Supports three types of statements
+ * - comparison: (field)-lt|le|eq|ge|gt|like(value)
+ * - negation: -not(filter)
+ * - conjunction/disjunction: (filter)-and|or(filter)
+ * Supported conditions are comparisons (<, <=, =, >=, >) and substring match (LIKE).
+ *
+ */
+export class OINODbQueryFilter extends OINOQueryFilter {
+
+    private static operatorToSql(filter: OINOQueryFilter):string {
+        switch (filter.operator) {
+            case "and": return " AND "
+            case "or": return " OR "
+            case "not": return "NOT "
+            case "lt": return " < "
+            case "le": return " <= "
+            case "eq": return " = "
+            case "ne": return " != "
+            case "ge": return " >= "
+            case "gt": return " > "
+            case "like": return " LIKE "
+            case "isnull": return " IS NULL"
+            case "isNotNull": return " IS NOT NULL"
+        }
+        return " "
+    }
+
+    /**
+     * Print filter as SQL condition based on the datamodel of the API.
+     * 
+     * @param dataModel data model (and database) to use for formatting of values
+     *
+     */
+    static printSql(filter: OINOQueryFilter, dataModel:OINODbDataModel):string {
+        if (filter.isEmpty()) {
+            return ""
+        }
+        let result:string = ""
+        let field:OINODataField|null = null
+        if (filter.leftSide instanceof OINOQueryFilter) {
+            result += OINODbQueryFilter.printSql(filter.leftSide, dataModel)
+        } else {
+            field = dataModel.findFieldByName(filter.leftSide as string)
+            if (!field) {
+                OINOLog.error("@oino-ts/db", "OINODbQueryFilter", "toSql", "Invalid field!", {field:filter.leftSide})
+                throw new Error(OINO_ERROR_PREFIX + ": OINODbQueryFilter.toSql - Invalid field '" + filter.leftSide + "'") // invalid field name could be a security risk, stop processing
+            }
+            result += dataModel.api.datasource.printColumnName(field.name)
+        }
+        result += OINODbQueryFilter.operatorToSql(filter)
+        if (filter.rightSide instanceof OINOQueryFilter) {
+            result += OINODbQueryFilter.printSql(filter.rightSide, dataModel)
+
+        } else if (filter.operator == OINOQueryNullCheck.isnull || filter.operator == OINOQueryNullCheck.isNotNull) {
+            // nothing to do, IS NULL and IS NOT NULL do not have a right side
+        } else {
+            const value = field!.deserializeCell(filter.rightSide as string)
+            if ((value == null) || (value === "")) {
+                OINOLog.error("@oino-ts/db", "OINODbQueryFilter", "toSql", "Invalid value!", {value:value})
+                throw new Error(OINO_ERROR_PREFIX + ": OINODbQueryFilter.toSql - Invalid value '" + value + "'") // invalid value could be a security risk, stop processing
+            }
+            result += field!.printCellAsValue(value)
+        }
+        result = "(" + result + ")"
+        OINOLog.debug("@oino-ts/db", "OINODbQueryFilter", "toSql", "Result", {sql:result})
+        return result
+    }
+}
+
+/**
+ * Class for ordering select results on a number of columns. 
+ *
+ */
+export class OINODbQueryOrder extends OINOQueryOrder {
+
+    /**
+     * Print order as SQL condition based on the datamodel of the API.
+     * 
+     * @param order order instance
+     * @param dataModel data model (and database) to use for formatting of values
+     *
+     */
+    static printSql(order: OINOQueryOrder, dataModel:OINODbDataModel):string {
+        if (order.isEmpty()) {
+            return ""
+        }
+        let result:string = ""
+        for (let i=0; i<order.columns.length; i++) {
+            const field:OINODataField|null = dataModel.findFieldByName(order.columns[i])
+            if (!field) {
+                OINOLog.error("@oino-ts/db", "OINODbQueryOrder", "toSql", "Invalid field!", {field:order.columns[i]})
+                throw new Error(OINO_ERROR_PREFIX + ": OINODbQueryOrder.toSql - Invalid field '" + order.columns[i] + "'") // invalid field name could be a security risk, stop processing
+            }
+            if (result) {
+                result += ","
+            }
+            result += dataModel.api.datasource.printColumnName(field.name) + " "
+            if (order.descending[i]) {
+                result += "DESC"
+            } else {
+                result += "ASC"
+            }
+        }
+        OINOLog.debug("@oino-ts/db", "OINODbQueryOrder", "toSql", "Result", {sql:result})
+        return result
+    }
+}
+
+/**
+ * Class for limiting the number of results. 
+ *
+ */
+export class OINODbQueryLimit extends OINOQueryLimit {
+
+    /**
+     * Print order as SQL condition based on the datamodel of the API.
+     * 
+     * @param limit limit instance
+     * @param dataModel data model (and database) to use for formatting of values
+     *
+     */
+    static printSql(limit: OINOQueryLimit, dataModel:OINODbDataModel):string {
+        if (limit.isEmpty()) {
+            return ""
+        }
+        let result:string = limit.limit.toString()
+        if (limit.page > 0) {
+            result += " OFFSET " + (limit.limit * (limit.page-1) + 1).toString()
+        }
+        OINOLog.debug("@oino-ts/db", "OINODbQueryLimit", "toSql", "Result", {sql:result})
+        return result
+    }
+}
+
+/**
+ * Class for limiting the number of results. 
+ *
+ */
+export class OINODbQueryAggregate extends OINOQueryAggregate {
+
+    /**
+     * Print non-aggregated fields as SQL GROUP BY-condition based on the datamodel of the API.
+     * 
+     * @param aggregate aggregate instance
+     * @param dataModel data model (and database) to use for formatting of values
+     * @param select what fields to select 
+     *
+     */
+    static printSql(aggregate: OINOQueryAggregate, dataModel:OINODataModel, select?:OINOQuerySelect):string {
+        if (aggregate.isEmpty()) {
+            return ""
+        }
+        let result:string = ""
+        for (let i=0; i<dataModel.fields.length; i++) {
+            const f = dataModel.fields[i]
+            if ((select?.isSelected(f.name) || (f.fieldParams.isPrimaryKey == true)) && (aggregate.fields.includes(f.name) == false)) {
+                result += f.printColumnName() + ","
+            }
+        }
+        result = result.substring(0, result.length-1)
+        OINOLog.debug("@oino-ts/db", "OINODbQueryAggregate", "toSql", "Result", {sql:result})
+        return result
+    }
+
+    /**
+     * Print non-aggregated fields as SQL GROUP BY-condition based on the datamodel of the API.
+     * 
+     * @param dataModel data model (and database) to use for formatting of values
+     * @param select what fields to select 
+     *
+     */
+    static printColumnNames(aggregate: OINOQueryAggregate, dataModel:OINODataModel, select?:OINOQuerySelect):string {
+        let result:string = ""
+        for (let i=0; i<dataModel.fields.length; i++) {
+            const f:OINODataField = dataModel.fields[i]
+            if ((select?.isSelected(f.name) === false) && (f.fieldParams.isPrimaryKey == false)) { // if a field is not selected, we include an aggregated constant (min of const string) and correct fieldname instead so that dimensions of the data don't change, it does not need a group by but no unnecessary data is fetched
+                result += OINOQueryAggregateFunctions.min + "(" + f.datasource.printStringValue("") + ") as " + f.printColumnName()+","
+
+            } else {
+                const aggregate_index = aggregate.fields.indexOf(f.name)
+                const col_name = f.printColumnName()
+                if (aggregate_index >= 0) {
+                    result += aggregate.functions[aggregate_index] + "(" + col_name + ") as " + col_name + ","
+                } else {
+                    result += col_name + ","
+                }
+            }
+        }
+        return result.substring(0, result.length-1)
+    }
+}

package/src/index.ts

@@ -1,118 +1,6 @@
-import { Buffer } from "node:buffer";
-import { OINODb } from "./OINODb.js"
-import { OINODbDataField } from "./OINODbDataField.js"
-import { OINODbSqlAggregate, OINODbSqlFilter, OINODbSqlLimit, OINODbSqlOrder, OINODbSqlSelect } from "./OINODbSqlParams.js"
-
-export { OINODbApiResult, OINODbHtmlTemplate, OINODbApi, OINODbApiRequest, type OINODbApiRequestInit, type OINODbApiData } from "./OINODbApi.js"
-export { OINODbDataModel } from "./OINODbDataModel.js"
-export { OINODbModelSet } from "./OINODbModelSet.js"
-export { OINODbDataField, OINOBooleanDataField, OINONumberDataField, OINOStringDataField, OINOBlobDataField, OINODatetimeDataField } from "./OINODbDataField.js"
-export { OINODbDataSet, OINODbMemoryDataSet, OINODb } from "./OINODb.js"
-export { OINODbSqlFilter, OINODbSqlOrder, OINODbSqlComparison, OINODbSqlLimit, OINODbSqlBooleanOperation, OINODbSqlAggregate, OINODbSqlAggregateFunctions, OINODbSqlSelect, OINODbSqlNullCheck } from "./OINODbSqlParams.js"
-export { OINODbConfig } from "./OINODbConfig.js"
-export { OINODbFactory } from "./OINODbFactory.js"
-export { OINODbSwagger } from "./OINODbSwagger.js"
-export { OINODbParser } from "./OINODbParser.js"
-
-/** API parameters */
-export type OINODbApiParams = {
-    /** Name of the api */
-    apiName: string 
-    /** Name of the database table */
-    tableName: string 
-    /** Reject values that exceed field max length (behaviour on such is platform dependent) */
-    failOnOversizedValues?: Boolean
-    /** Reject PUT-requests that contain values for autoinc-type fields */
-    failOnUpdateOnAutoinc?: boolean
-    /** Reject POST-requests without primary key value (can work if DB-side ) */
-    failOnInsertWithoutKey?: boolean
-    /** Reject POST-requests without primary key value (can work if DB-side ) */
-    failOnAnyInvalidRows?: boolean
-    /** Treat date type fields as just strings and use the native formatting instead of the ISO 8601 format */
-    useDatesAsString?: Boolean
-    /** Include given fields from the API and exclude rest (if defined) */
-    includeFields?:string[],
-    /** Exclude all fields with this prefix from the API */
-    excludeFieldPrefix?:string
-    /** Exclude given fields from the API and include rest (if defined) */
-    excludeFields?:string[],
-    /** Enable hashids for numeric primarykeys by adding a 32 char key */
-    hashidKey?:string,
-    /** Set (minimum) length (12-32 chars) of the hashids */
-    hashidLength?:number,
-    /** Make hashids static per row/table */
-    hashidStaticIds?: boolean,
-    /** Name of field that has the modified field */
-    cacheModifiedField?:string,
-    /** Return inserted id values */
-    returnInsertedIds?: boolean
-}
-
-/** 
- * Database class (constructor) type 
- * @param dbParams database parameters
- */
-export type OINODbConstructor = new (dbParams:OINODbParams) => OINODb
-
-/** Database parameters */
-export type OINODbParams = {
-    /** Name of the database class (e.g. OINODbPostgresql)  */
-    type: string
-    /** Connection URL, either file://-path or an IP-address or an HTTP-url */
-    url: string
-    /** Name of the database */
-    database: string 
-    /** TCP port of the database */
-    port?: number
-    /** Username used to authenticate */
-    user?: string
-    /** Password used to authenticate */
-    password?: string
-}
-
-/** Field parameters in database */
-export type OINODbDataFieldParams = {
-    /** 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
-}
-
-/** 
- * Callback to filter data fields 
- * @param field fields to filter
- */
-export type OINODbDataFieldFilter = (field:OINODbDataField) => Boolean
-
-/** Request options */
-export type OINODbSqlParams = {
-    /** Additional SQL select where-conditions */
-    filter?:OINODbSqlFilter,
-    /** SQL result ordering conditions */
-    order?:OINODbSqlOrder
-    /** SQL result limit condition */
-    limit?:OINODbSqlLimit
-    /** SQL aggregation functions */
-    aggregate?:OINODbSqlAggregate
-    /** SQL select condition */
-    select?:OINODbSqlSelect
-}
-
-/** 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 OINODB_EMPTY_ROW:OINODataRow = []
-/** Empty row array instance */
-export const OINODB_EMPTY_ROWS:OINODataRow[] = []
-/** Constant for undefined values */
-export const OINODB_UNDEFINED = "" // original idea was to have a defined literal that get's swapped back to undefined, but current implementation just leaves it out at serialization (so value does not matter)
-
-/** Key-value collection */
-export type OINOValues = Record<string, string>
-
+export { OINODb } from "./OINODb.js"
+export { OINODbDataModel } from "./OINODbDataModel.js"
+export { OINODbFactory } from "./OINODbFactory.js"
+export { OINODbApi } from "./OINODbApi.js"
+export { OINODbQueryFilter, OINODbQueryOrder, OINODbQueryLimit, OINODbQueryAggregate } from "./OINODbQueryParams.js"
+export { type OINODbConstructor, type OINODbParams, OINODB_UNDEFINED } from "./OINODbConstants.js"

package/src/OINODbConfig.ts

@@ -1,98 +0,0 @@
-/** Set the name of the OINO ID field (default \_OINOID\_) */
-
-export class OINODbConfig {
-    /** Name of the synthetic OINO ID field */
-    static OINODB_ID_FIELD:string = "_OINOID_"
-    /** Private key separator of the synthetic OINO ID field */
-    static OINODB_ID_SEPARATOR:string = "_"
-    private static OINODB_ID_SEPARATOR_ESCAPED:string = "%"
-
-    /** Name of the OINODbSqlFilter-parameter in request */
-    static OINODB_SQL_FILTER_PARAM:string = "oinosqlfilter"
-
-    /** Name of the OINODbSqlOrder-parameter in request */
-    static OINODB_SQL_ORDER_PARAM:string = "oinosqlorder"
-
-    /** Name of the OINODbSqlLimit-parameter in request */
-    static OINODB_SQL_LIMIT_PARAM:string = "oinosqllimit"
-
-    /** Name of the OINODbSqlAggregate-parameter in request */
-    static OINODB_SQL_AGGREGATE_PARAM:string = "oinosqlaggregate"
-
-    /** Name of the OINODbSqlSelect-parameter in request */
-    static OINODB_SQL_SELECT_PARAM:string = "oinosqlselect"
-
-    /** 
-     * Set the name of the OINO ID field 
-     * @param idField name of the OINO ID field 
-     */
-    static setOinoIdField(idField: string) {
-        if (idField) {
-            OINODbConfig.OINODB_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)) {
-            OINODbConfig.OINODB_ID_SEPARATOR = idSeparator;
-            OINODbConfig.OINODB_ID_SEPARATOR_ESCAPED = '%' + idSeparator.charCodeAt(0).toString(16);
-        }
-    }
-
-    /**
-     * 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 += OINODbConfig.OINODB_ID_SEPARATOR
-            } 
-            result += encodeURIComponent(primaryKeys[i] as string).replaceAll(OINODbConfig.OINODB_ID_SEPARATOR, OINODbConfig.OINODB_ID_SEPARATOR_ESCAPED)
-        }
-        return result
-    }
-
-    /** 
-     * Set the name of the OINODbSqlFilter-param field 
-     * 
-     * @param sqlFilterParam name of the http parameter with `OINODbSqlFilter` definition
-     * 
-     */
-    static setOinoSqlFilterParam(sqlFilterParam: string) {
-        if (sqlFilterParam) {
-            OINODbConfig.OINODB_SQL_FILTER_PARAM = sqlFilterParam;
-        }
-    }
-
-    /** 
-     * Set the name of the OINODbSqlOrder-param field 
-     * 
-     * @param sqlOrderParam name of the http parameter with `OINODbSqlOrder` definition
-     * 
-     */
-    static setOinoSqlOrderParam(sqlOrderParam: string) {
-        if (sqlOrderParam) {
-            OINODbConfig.OINODB_SQL_ORDER_PARAM = sqlOrderParam;
-        }
-    }
-
-    /** 
-     * Set the name of the OINODbSqlLimit-param field 
-     * 
-     * @param sqlLimitParam name of the http parameter with `OINODbSqlLimit` definition
-     * 
-     */
-    static setOinoSqlLimitParam(sqlLimitParam: string) {
-        if (sqlLimitParam) {
-            OINODbConfig.OINODB_SQL_LIMIT_PARAM = sqlLimitParam;
-        }
-    }
-}