@oino-ts/db 0.21.2 → 1.0.1

package/dist/types/index.d.ts

@@ -1,110 +1,6 @@
-/// <reference types="node" />
-/// <reference types="node" />
-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 { OINODb } from "./OINODb.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 declare const OINODB_EMPTY_ROW: OINODataRow;
-/** Empty row array instance */
-export declare const OINODB_EMPTY_ROWS: OINODataRow[];
-/** Constant for undefined values */
-export declare const OINODB_UNDEFINED = "";
-/** Key-value collection */
-export type OINOValues = Record<string, string>;
+export { OINODbApi } from "./OINODbApi.js";
+export { OINODbQueryFilter, OINODbQueryOrder, OINODbQueryLimit, OINODbQueryAggregate } from "./OINODbQueryParams.js";
+export { type OINODbConstructor, type OINODbParams, OINODB_UNDEFINED } from "./OINODbConstants.js";

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "@oino-ts/db",
-  "version": "0.21.2",
-  "description": "OINO TS library package for publishing an SQL database tables as a REST API.",
-  "author": "Matias Kiviniemi (pragmatta)",
-  "license": "MPL-2.0",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/pragmatta/oino-ts.git"
-  },
-  "keywords": [
-    "sql",
-    "database",
-    "rest-api",
-    "typescript",
-    "library"
-  ],
-  "main": "./dist/cjs/index.js",
-  "module": "./dist/esm/index.js",
-  "types": "./dist/types/index.d.ts",
-  "dependencies": {
-    "@oino-ts/common": "0.21.2",
-    "oino-ts": "file:.."
-  },
-  "devDependencies": {
-    "@oino-ts/types": "0.21.2",
-    "@types/bun": "^1.1.14",
-    "@types/node": "^20.21.20",
-    "typescript": "~5.9.0"
-  },
-  "files": [
-    "src/*.ts",
-    "dist/cjs/*.js",
-    "dist/esm/*.js",
-    "dist/types/*.d.ts"
-  ]
-}
+{
+  "name": "@oino-ts/db",
+  "version": "1.0.1",
+  "description": "OINO TS library package for publishing an SQL database tables as a REST API.",
+  "author": "Matias Kiviniemi (pragmatta)",
+  "license": "MPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pragmatta/oino-ts.git"
+  },
+  "keywords": [
+    "sql",
+    "database",
+    "rest-api",
+    "typescript",
+    "library"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "dependencies": {
+    "@oino-ts/common": "1.0.1",
+    "oino-ts": "file:.."
+  },
+  "devDependencies": {
+    "@oino-ts/types": "1.0.1",
+    "@types/bun": "^1.1.14",
+    "@types/node": "^21.0.10",
+    "typescript": "~5.9.0"
+  },
+  "files": [
+    "src/*.ts",
+    "dist/cjs/*.js",
+    "dist/esm/*.js",
+    "dist/types/*.d.ts"
+  ]
+}

package/src/OINODb.ts

@@ -1,348 +1,99 @@
-/*
- * 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, OINOResult } from "@oino-ts/common"
-import { OINODbParams, OINODbApi, OINODataCell, OINODataRow, OINODB_EMPTY_ROW } from "./index.js"
-
-/**
- * Base class for database abstraction, implementing methods for connecting, making queries and parsing/formatting data 
- * between SQL and serialization formats.
- *
- */
-export abstract class OINODb {
-    
-    protected _params:OINODbParams
-
-    /** Name of the database */
-    readonly name:string
-
-    isConnected:boolean = false
-    isValidated:boolean = false
-
-    /**
-     * Constructor for `OINODb`.
-     * @param params database parameters
-     */
-    constructor(params:OINODbParams) {
-        this._params = { ...params } // make a shallow copy of params so that changes to them do not affect the original object
-        this.name = this._params.database
-    }
-
-    /**
-     * 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 printSqlTablename(sqlTable:string): string
-
-    /**
-     * Print a column name with correct SQL escaping.
-     * 
-     * @param sqlColumn name of the column
-     *
-     */
-    abstract printSqlColumnname(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 printCellAsSqlValue(cellValue:OINODataCell, sqlType: string): string
-
-    /**
-     * Print a single string value as valid sql literal
-     * 
-     * @param sqlString string value
-     *
-     */
-    abstract printSqlString(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 parseSqlValueAsCell(sqlValue:OINODataCell, sqlType: string): OINODataCell
-    
-    /**
-     * Execute a select operation.
-     * 
-     * @param sql SQL statement.
-     *
-     */
-    abstract sqlSelect(sql:string): Promise<OINODbDataSet>
-
-    /**
-     * Execute other sql operations.
-     * 
-     * @param sql SQL statement.
-     *
-     */
-    abstract sqlExec(sql:string): Promise<OINODbDataSet>
-
-    /**
-     * Initialize a data model by getting the SQL schema and populating OINODbDataFields of 
-     * the model.
-     * 
-     * @param api api which data model to initialize.
-     *
-     */
-    abstract initializeApiDatamodel(api:OINODbApi): Promise<void>
-
-    /**
-     * Print SQL select statement with DB specific formatting.
-     * 
-     * @param tableName - The name of the table to select from.
-     * @param columnNames - The columns to be selected.
-     * @param whereCondition - The WHERE clause to filter the results.
-     * @param orderCondition - The ORDER BY clause to sort the results.
-     * @param limitCondition - The LIMIT clause to limit the number of results.
-     * @param groupByCondition - The GROUP BY clause to group the results.
-     * 
-     */
-    printSqlSelect(tableName:string, columnNames:string, whereCondition:string, orderCondition:string, limitCondition:string, groupByCondition: string): string {
-        let result:string = "SELECT " + columnNames + " FROM " + tableName;
-        if (whereCondition != "")  {
-            result += " WHERE " + whereCondition
-        }
-        if (groupByCondition != "") {
-            result += " GROUP BY " + groupByCondition 
-        }
-        if (orderCondition != "") {
-            result += " ORDER BY " + orderCondition 
-        }
-        if (limitCondition != "") {
-            result += " LIMIT " + limitCondition 
-        }
-        result += ";"
-        return result;
-    }
-
-    /**
-     * Print SQL select statement with DB specific formatting.
-     * 
-     * @param tableName - The name of the table to select from.
-     * @param columns - The columns to be selected.
-     * @param values - The values to be inserted.
-     * @param returnIdFields - the id fields to return if returnIds is true (if supported by the database)
-     * 
-     */
-    printSqlInsert(tableName:string, columns:string, values:string, returnIdFields?:string[]): string {
-        let result = "INSERT INTO " + tableName + " (" + columns + ") VALUES (" + values + ")"
-        if (returnIdFields) {
-            result += " RETURNING " + returnIdFields.join(",")
-        }
-        result += ";"
-        return result;
-    }
-
-}
-
-/**
- * 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
- * `OINODbDataSet` will serve it out consistently.
- *
- */
-
-export abstract class OINODbDataSet extends OINOResult {
-    private _data: unknown;
-
-    /** Error messages */
-    readonly messages: string[];
-
-    /**
-     * Constructor for `OINODbDataSet`.
-     *
-     * @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;
-    }
-    /**
-     * Checks if the messages contain errors.
-     *
-     */
-    getFirstError(): 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 OINODbMemoryDataSet extends OINODbDataSet {
-    private _rows: OINODataRow[];
-    private _currentRow: number;
-    private _eof: boolean;
-
-    /**
-     * Constructor of `OINODbMemoryDataSet`.
-     *
-     * @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 OINODB_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;
-    }
-}
-
-
+/*
+ * 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 { OINODataSet, OINODataSource } from "@oino-ts/common"
+import { OINODbParams } from "./OINODbConstants.js"
+
+/**
+ * Base class for database abstraction, implementing methods for connecting, making queries and parsing/formatting data 
+ * between SQL and serialization formats.
+ *
+ */
+export abstract class OINODb extends OINODataSource {
+    
+    protected readonly dbParams:OINODbParams
+
+    /** Name of the database */
+    readonly name:string
+
+    isConnected:boolean = false
+    isValidated:boolean = false
+
+    /**
+     * Constructor for `OINODb`.
+     * @param params database parameters
+     */
+    constructor(params:OINODbParams) {
+        super()
+        this.dbParams = { ...params } // make a shallow copy of params so that changes to them do not affect the original object
+        this.name = this.dbParams.database
+    }
+    
+    /**
+     * Execute a select operation.
+     * 
+     * @param sql SQL statement.
+     *
+     */
+    abstract sqlSelect(sql:string): Promise<OINODataSet>
+
+    /**
+     * Execute other sql operations.
+     * 
+     * @param sql SQL statement.
+     *
+     */
+    abstract sqlExec(sql:string): Promise<OINODataSet>
+
+    /**
+     * Print SQL select statement with DB specific formatting.
+     * 
+     * @param tableName - The name of the table to select from.
+     * @param columnNames - The columns to be selected.
+     * @param whereCondition - The WHERE clause to filter the results.
+     * @param orderCondition - The ORDER BY clause to sort the results.
+     * @param limitCondition - The LIMIT clause to limit the number of results.
+     * @param groupByCondition - The GROUP BY clause to group the results.
+     * 
+     */
+    printSqlSelect(tableName:string, columnNames:string, whereCondition:string, orderCondition:string, limitCondition:string, groupByCondition: string): string {
+        let result:string = "SELECT " + columnNames + " FROM " + tableName;
+        if (whereCondition != "")  {
+            result += " WHERE " + whereCondition
+        }
+        if (groupByCondition != "") {
+            result += " GROUP BY " + groupByCondition 
+        }
+        if (orderCondition != "") {
+            result += " ORDER BY " + orderCondition 
+        }
+        if (limitCondition != "") {
+            result += " LIMIT " + limitCondition 
+        }
+        result += ";"
+        return result;
+    }
+
+    /**
+     * Print SQL select statement with DB specific formatting.
+     * 
+     * @param tableName - The name of the table to select from.
+     * @param columns - The columns to be selected.
+     * @param values - The values to be inserted.
+     * @param returnIdFields - the id fields to return if returnIds is true (if supported by the database)
+     * 
+     */
+    printSqlInsert(tableName:string, columns:string, values:string, returnIdFields?:string[]): string {
+        let result = "INSERT INTO " + tableName + " (" + columns + ") VALUES (" + values + ")"
+        if (returnIdFields) {
+            result += " RETURNING " + returnIdFields.join(",")
+        }
+        result += ";"
+        return result;
+    }
+
+}
+