@oino-ts/types 0.21.2 → 1.0.0

package/db/src/OINODbDataField.d.ts

@@ -0,0 +1,210 @@
+import { OINODbDataFieldParams, OINODataCell, OINODb } from "./index.js";
+/**
+ * Base class for a column of data responsible for appropriatelly serializing/deserializing the data.
+ *
+ */
+export declare class OINODbDataField {
+    /** OINODB reference*/
+    readonly db: OINODb;
+    /** Name of the field */
+    readonly name: string;
+    /** Internal type of field*/
+    readonly type: string;
+    /** SQL type of the field */
+    readonly sqlType: string;
+    /** Maximum length of the field (or 0) */
+    readonly maxLength: number;
+    /** Parameters for the field */
+    readonly fieldParams: OINODbDataFieldParams;
+    /**
+     * Constructor for a data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param type internal type of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(db: OINODb, name: string, type: string, sqlType: string, fieldParams: OINODbDataFieldParams, maxLength?: number);
+    /**
+     * Pring debug information for the field
+     *
+     * @param length length of the debug output (or 0 for as long as needed)
+     *
+     */
+    printColumnDebug(length?: number): string;
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal: OINODataCell): string | null | undefined;
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value: string | null | undefined): OINODataCell;
+    /**
+     * Print data cell (from deserialization) as SQL-string.
+     *
+     * @param cellVal cell value
+     *
+     */
+    printCellAsSqlValue(cellVal: OINODataCell): string;
+    /**
+     * Print name of column as SQL.
+     *
+     */
+    printSqlColumnName(): string;
+}
+/**
+ * Specialised class for a string column.
+ *
+ */
+export declare class OINOStringDataField extends OINODbDataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(db: OINODb, name: string, sqlType: string, fieldParams: OINODbDataFieldParams, maxLength: number);
+}
+/**
+ * Specialised class for a boolean column.
+ *
+ */
+export declare class OINOBooleanDataField extends OINODbDataField {
+    /**
+     * Constructor for a boolean data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(db: OINODb, name: string, sqlType: string, fieldParams: OINODbDataFieldParams);
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal: OINODataCell): string | null | undefined;
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value: string | null | undefined): OINODataCell;
+}
+/**
+ * Specialised class for a number column.
+ *
+ */
+export declare class OINONumberDataField extends OINODbDataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(db: OINODb, name: string, sqlType: string, fieldParams: OINODbDataFieldParams);
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal: OINODataCell): string | null | undefined;
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value: string | null | undefined): OINODataCell;
+}
+/**
+ * Specialised class for a blob column.
+ *
+ */
+export declare class OINOBlobDataField extends OINODbDataField {
+    /**
+     * Constructor for a blob data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(db: OINODb, name: string, sqlType: string, fieldParams: OINODbDataFieldParams, maxLength: number);
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal: OINODataCell): string | null | undefined;
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value: string | null | undefined): OINODataCell;
+}
+/**
+ * Specialised class for a datetime column.
+ *
+ */
+export declare class OINODatetimeDataField extends OINODbDataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param db OINODb reference
+     * @param name name of the field
+     * @param sqlType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(db: OINODb, name: string, sqlType: string, fieldParams: OINODbDataFieldParams);
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     *
+     */
+    serializeCell(cellVal: OINODataCell): string | null | undefined;
+    /**
+     * Serialize cell value in the given content format.
+     *
+     * @param cellVal cell value
+     * @param locale locale-object to format datetimes with
+     *
+     */
+    serializeCellWithLocale(cellVal: OINODataCell, locale: Intl.DateTimeFormat): string | null | undefined;
+    /**
+     * Parce cell value from string using field type specific formatting rules.
+     *
+     * @param value string value
+     *
+     */
+    deserializeCell(value: string | null | undefined): OINODataCell;
+}

package/db/src/OINODbDataModel.d.ts

@@ -0,0 +1,55 @@
+import { OINODataModel, OINODataField, OINODataRow, OINOQueryParams } from "@oino-ts/common";
+import { OINODbApi } from "./OINODbApi.js";
+/**
+ * OINO Datamodel object for representing one database table and it's columns.
+ *
+ */
+export declare class OINODbDataModel extends OINODataModel {
+    /** Database refererence of the table */
+    readonly dbApi: OINODbApi;
+    /** 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: OINODbApi);
+    private _printColumnNames;
+    private _printSqlInsertColumnsAndValues;
+    private _printSqlUpdateValues;
+    private _printSqlPrimaryKeyCondition;
+    private _printSqlPrimaryKeyColumns;
+    /**
+     * Print SQL select statement using optional id and filter.
+     *
+     * @param id OINO ID (i.e. combined primary key values)
+     * @param params OINO reqest params
+     *
+     */
+    printSqlSelect(id: string, params: OINOQueryParams): string;
+    /**
+     * Print SQL insert statement from one data row.
+     *
+     * @param row one row of data in the data model
+     *
+     */
+    printSqlInsert(row: OINODataRow): string;
+    /**
+     * Print SQL insert statement from one data row.
+     *
+     * @param id OINO ID (i.e. combined primary key values)
+     * @param row one row of data in the data model
+     *
+     */
+    printSqlUpdate(id: string, row: OINODataRow): string;
+    /**
+     * Print SQL delete statement for id.
+     *
+     * @param id OINO ID (i.e. combined primary key values)
+     *
+     */
+    printSqlDelete(id: string): string;
+}

package/db/src/OINODbDataSet.d.ts

@@ -0,0 +1,95 @@
+import { OINODataRow } from "./index.js";
+/**
+ * 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 declare abstract class OINODbDataSet {
+    private _data;
+    /** 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[]);
+    /**
+     * 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;
+    /**
+     * Checks if the messages contain errors.
+     *
+     */
+    hasErrors(): boolean;
+    /**
+     * Checks if the messages contain errors.
+     *
+     */
+    getFirstError(): string;
+}
+/**
+ * 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 declare class OINODbMemoryDataSet extends OINODbDataSet {
+    private _rows;
+    private _currentRow;
+    private _eof;
+    /**
+     * 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[]);
+    /**
+     * Is data set empty.
+     *
+     */
+    isEmpty(): boolean;
+    /**
+     * Is there no more content, i.e. either dataset is empty or we have moved beyond last line
+     *
+     */
+    isEof(): boolean;
+    /**
+     * Attempts to moves dataset to the next row, possibly waiting for more data to become available. Returns !isEof().
+     *
+     */
+    next(): Promise<boolean>;
+    /**
+     * Gets current row of data.
+     *
+     */
+    getRow(): OINODataRow;
+    /**
+     * Rewinds data set to the first row, returns !isEof().
+     *
+     */
+    first(): boolean;
+}

package/db/src/OINODbFactory.d.ts

@@ -0,0 +1,34 @@
+import { OINOApiParams } from "@oino-ts/common";
+import { OINODbParams, OINODbConstructor } from "./OINODbConstants.js";
+import { OINODbApi } from "./OINODbApi.js";
+import { OINODb } from "./OINODb.js";
+/**
+ * Static factory class for easily creating things based on data
+ *
+ */
+export declare class OINODbFactory {
+    private static _dbRegistry;
+    /**
+     * 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;
+    /**
+     * 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 createDb(params: OINODbParams, connect?: boolean, validate?: boolean): Promise<OINODb>;
+    /**
+     * Create API from parameters and calls initDatamodel on the datamodel.
+     *
+     * @param db databased used in API
+     * @param params parameters of the API
+     */
+    static createApi(db: OINODb, params: OINOApiParams): Promise<OINODbApi>;
+}

package/db/src/OINODbModelSet.d.ts

@@ -0,0 +1,62 @@
+import { OINOContentType } from "@oino-ts/common";
+import { OINODbDataSet, OINODbDataModel, OINODataCell, OINODbSqlParams } from "./index.js";
+/**
+ * Class for dataset based on a data model that can be serialized to
+ * a supported format:
+ * - JSON (application/json)
+ * - CSV (text/csv)
+ *
+ */
+export declare class OINODbModelSet {
+    /** Reference to datamodel */
+    readonly datamodel: OINODbDataModel;
+    /** Reference to data set */
+    readonly dataset: OINODbDataSet;
+    /** SQL parameters */
+    readonly sqlParams?: OINODbSqlParams;
+    /** Collection of errors */
+    errors: string[];
+    /**
+     * Constructor for `OINODbModelSet`.
+     *
+     * @param datamodel data model
+     * @param dataset data set
+     * @param sqlParams SQL parameters
+     */
+    constructor(datamodel: OINODbDataModel, dataset: OINODbDataSet, sqlParams?: OINODbSqlParams);
+    private _encodeAndHashFieldValue;
+    private _writeRowJson;
+    private _writeStringJson;
+    private _writeHeaderCsv;
+    private _writeRowCsv;
+    private _writeStringCsv;
+    private _writeRowFormdataParameterBlock;
+    private _writeRowFormdataFileBlock;
+    private _writeRowFormdata;
+    private _writeStringFormdata;
+    private _writeRowUrlencode;
+    private _writeStringUrlencode;
+    private _exportRow;
+    /**
+     * Serialize model set in the given format.
+     *
+     * @param [contentType=OINOContentType.json] serialization content type
+     *
+     */
+    writeString(contentType?: OINOContentType): Promise<string>;
+    /**
+     * Get value of given field in the current row. Undefined if no rows,
+     * field not found or value does not exist.
+     *
+     * @param fieldName name of the field
+     * @param serialize serialize the value
+     *
+     */
+    getValueByFieldName(fieldName: string, serialize?: boolean): OINODataCell;
+    /**
+     * Export all rows as a record with OINOId as key and object with row cells as values.
+     *
+     * @param idFieldName optional field name to use as key instead of OINOId
+     */
+    exportAsRecord(idFieldName?: string): Promise<Record<string, any>>;
+}

package/db/src/OINODbParser.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { Buffer } from "node:buffer";
+import { OINOContentType } from "@oino-ts/common";
+import { OINODbDataModel, OINODataRow } from "./index.js";
+/**
+ * Static factory class for easily creating things based on data
+ *
+ */
+export declare class OINODbParser {
+    /**
+     * Create data rows from request body based on the datamodel.
+     *
+     * @param datamodel datamodel of the api
+     * @param data data as either serialized string or unserialized JS object or OINODataRow-array or Buffer/Uint8Array binary data
+     * @param contentType content type of the data
+     * @param multipartBoundary multipart boundary for formdata parsing, if applicable
+     *
+     */
+    static createRows(datamodel: OINODbDataModel, data: string | object | Buffer | Uint8Array, contentType: OINOContentType, multipartBoundary?: string): OINODataRow[];
+    private static _createRowsFromText;
+    private static _createRowsFromBlob;
+    /**
+     * Create one data row from javascript object based on the datamodel.
+     * NOTE! Data assumed to be unserialized i.e. of the native type (string, number, boolean, Buffer)
+     *
+     * @param datamodel datamodel of the api
+     * @param data data as javascript object
+     *
+     */
+    private static _createRowFromObject;
+    private static _findCsvLineEnd;
+    private static _parseCsvLine;
+    private static _createRowFromCsv;
+    private static _createRowFromJsonObj;
+    private static _createRowFromJson;
+    private static _findMultipartBoundary;
+    private static _parseMultipartLine;
+    private static _multipartHeaderRegex;
+    private static _createRowFromFormdata;
+    private static _createRowFromUrlencoded;
+}

package/db/src/OINODbQueryParams.d.ts

@@ -0,0 +1,72 @@
+import { OINOQueryFilter, OINOQueryOrder, OINOQueryLimit, OINOQueryAggregate, 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 declare class OINODbQueryFilter extends OINOQueryFilter {
+    private static operatorToSql;
+    /**
+     * 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;
+}
+/**
+ * Class for ordering select results on a number of columns.
+ *
+ */
+export declare 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;
+}
+/**
+ * Class for limiting the number of results.
+ *
+ */
+export declare 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;
+}
+/**
+ * Class for limiting the number of results.
+ *
+ */
+export declare 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;
+    /**
+     * 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;
+}