@oino-ts/types 0.21.1 → 1.0.0

package/common/src/OINOConfig.d.ts

@@ -0,0 +1,63 @@
+/** Set the name of the OINO ID field (default \_OINOID\_) */
+export declare class OINOConfig {
+    /** Name of the synthetic OINO ID field */
+    static OINO_ID_FIELD: string;
+    /** Private key separator of the synthetic OINO ID field */
+    static OINO_ID_SEPARATOR: string;
+    private static OINO_ID_SEPARATOR_ESCAPED;
+    /** Name of the OINODbQueryFilter-parameter in request */
+    static OINO_QUERY_FILTER_PARAM: string;
+    /** Name of the OINODbQueryOrder-parameter in request */
+    static OINO_QUERY_ORDER_PARAM: string;
+    /** Name of the OINODbQueryLimit-parameter in request */
+    static OINO_QUERY_LIMIT_PARAM: string;
+    /** Name of the OINODbQueryAggregate-parameter in request */
+    static OINO_QUERY_AGGREGATE_PARAM: string;
+    /** Name of the OINODbSqlSelect-parameter in request */
+    static OINO_QUERY_SELECT_PARAM: string;
+    /**
+     * Set the name of the OINO ID field
+     * @param idField name of the OINO ID field
+     */
+    static setOinoIdField(idField: string): void;
+    /**
+     * Set the separator character of the OINO ID field
+     * @param idSeparator character to use as separator of id parts
+    */
+    static setOinoIdSeparator(idSeparator: string): void;
+    /**
+     * Print OINO ID for primary key values.
+     *
+     * @param primaryKeys an array of primary key values.
+     *
+     */
+    static printOINOId(primaryKeys: string[]): string;
+    /**
+     * Print OINO ID for primary key values.
+     *
+     * @param oinoid the OINO ID string to parse as primary key values.
+     *
+     */
+    static parseOINOId(oinoid: string): string[];
+    /**
+     * Set the name of the OINODbQueryFilter-param field
+     *
+     * @param sqlFilterParam name of the http parameter with `OINODbQueryFilter` definition
+     *
+     */
+    static setOinoQueryFilterParam(sqlFilterParam: string): void;
+    /**
+     * Set the name of the OINODbQueryOrder-param field
+     *
+     * @param sqlOrderParam name of the http parameter with `OINODbQueryOrder` definition
+     *
+     */
+    static setOinoQueryOrderParam(sqlOrderParam: string): void;
+    /**
+     * Set the name of the OINODbQueryLimit-param field
+     *
+     * @param sqlLimitParam name of the http parameter with `OINODbQueryLimit` definition
+     *
+     */
+    static setOinoQueryLimitParam(sqlLimitParam: string): void;
+}

package/common/src/OINOConstants.d.ts

@@ -0,0 +1,51 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { Buffer } from "node:buffer";
+/** OINO error message prefix */
+export declare const OINO_ERROR_PREFIX = "OINO ERROR";
+/** OINO warning message prefix */
+export declare const OINO_WARNING_PREFIX = "OINO WARNING";
+/** OINO info message prefix */
+export declare const OINO_INFO_PREFIX = "OINO INFO";
+/** OINO debug message prefix */
+export declare const OINO_DEBUG_PREFIX = "OINO DEBUG";
+/** Name of the OINOContentType-parameter request */
+export declare const OINO_REQUEST_TYPE_PARAM = "oinorequesttype";
+/** Name of the OINOContentType-parameter request */
+export declare const OINO_RESPONSE_TYPE_PARAM = "oinoresponsetype";
+/** Name of the query parameter that triggers a file download response */
+export declare const OINO_RESPONSE_DOWNLOAD_PARAM = "oinoresponsedownload";
+/**
+ * Supported content format mime-types
+ */
+export declare enum OINOContentType {
+    /** JSON encoded data */
+    json = "application/json",
+    /** CSV encoded data */
+    csv = "text/csv",
+    /** Multipart encoded form data */
+    formdata = "multipart/form-data",
+    /** URL encoded form data */
+    urlencode = "application/x-www-form-urlencoded",
+    /** HTML encoded data (output only) */
+    html = "text/html"
+}
+/** Field parameters in database */
+export type OINODataFieldParams = {
+    /** 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;
+};
+/** 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 OINO_EMPTY_ROW: OINODataRow;
+/** Empty row array instance */
+export declare const OINO_EMPTY_ROWS: OINODataRow[];

package/common/src/OINODataField.d.ts

@@ -0,0 +1,209 @@
+import { OINODataFieldParams, OINODataCell } from "./OINOConstants.js";
+import { OINODataSource } from "./OINODataSource.js";
+/**
+ * Base class for a column of data responsible for appropriatelly serializing/deserializing the data.
+ *
+ */
+export declare class OINODataField {
+    /** OINO data source reference*/
+    readonly datasource: OINODataSource;
+    /** Name of the field */
+    readonly name: string;
+    /** Internal type of field*/
+    readonly type: string;
+    /** SQL type of the field */
+    readonly nativeType: string;
+    /** Maximum length of the field (or 0) */
+    readonly maxLength: number;
+    /** Parameters for the field */
+    readonly fieldParams: OINODataFieldParams;
+    /**
+     * Constructor for a data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param type internal type of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(datasource: OINODataSource, name: string, type: string, nativeType: string, fieldParams: OINODataFieldParams, 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;
+    /**
+     * Print data cell (from deserialization) as SQL-string.
+     *
+     * @param cellVal cell value
+     *
+     */
+    printCellAsValue(cellVal: OINODataCell): string;
+    /**
+     * Print name of column as SQL.
+     *
+     */
+    printColumnName(): string;
+}
+/**
+ * Specialised class for a string column.
+ *
+ */
+export declare class OINOStringDataField extends OINODataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(datasource: OINODataSource, name: string, nativeType: string, fieldParams: OINODataFieldParams, maxLength: number);
+}
+/**
+ * Specialised class for a boolean column.
+ *
+ */
+export declare class OINOBooleanDataField extends OINODataField {
+    /**
+     * Constructor for a boolean data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(datasource: OINODataSource, name: string, nativeType: string, fieldParams: OINODataFieldParams);
+    /**
+     * 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 OINODataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(datasource: OINODataSource, name: string, nativeType: string, fieldParams: OINODataFieldParams);
+    /**
+     * 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 OINODataField {
+    /**
+     * Constructor for a blob data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     * @param maxLength maximum length of the field (or 0)
+     *
+     */
+    constructor(datasource: OINODataSource, name: string, nativeType: string, fieldParams: OINODataFieldParams, 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 OINODataField {
+    /**
+     * Constructor for a string data field
+     *
+     * @param datasource OINO data source reference
+     * @param name name of the field
+     * @param nativeType column type in database
+     * @param fieldParams parameters of the field
+     *
+     */
+    constructor(datasource: OINODataSource, name: string, nativeType: string, fieldParams: OINODataFieldParams);
+    /**
+     * 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;
+}
+/**
+ * Callback to filter data fields
+ * @param field fields to filter
+ */
+export type OINODataFieldFilter = (field: OINODataField) => Boolean;

package/common/src/OINODataModel.d.ts

@@ -0,0 +1,78 @@
+import { OINODataRow } from "./OINOConstants.js";
+import { OINOApi } from "./OINOApi.js";
+import { OINODataField, OINODataFieldFilter } from "./OINODataField.js";
+/**
+ * OINO Datamodel object for representing one database table and it's columns.
+ *
+ */
+export declare class OINODataModel {
+    private _fieldIndexLookup;
+    /** 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);
+    /**
+     * Add a field to the datamodel.
+     *
+     * @param field dataset field
+     *
+     */
+    addField(field: OINODataField): void;
+    /**
+     * Find a field of a given name if any.
+     *
+     * @param name name of the field to find
+     *
+     */
+    findFieldByName(name: string): OINODataField | null;
+    /**
+     * Find index of a field of a given name if any.
+     *
+     * @param name name of the field to find
+     *
+     */
+    findFieldIndexByName(name: string): number;
+    /**
+     * 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[];
+    /**
+     * 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): string[];
+    /**
+     * 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): string;
+    /**
+     * Print debug information about the fields.
+     *
+     * @param separator string to separate field prints
+     *
+     */
+    printDebug(separator?: string): string;
+    /**
+     * Print all public properties (db, table name, fields) of the datamodel. Used
+     * in automated testing validate schema has stayed the same.
+     *
+     */
+    printFieldPublicPropertiesJson(): string;
+}

package/common/src/OINODataSource.d.ts

@@ -0,0 +1,184 @@
+import { OINODataCell, OINODataRow } 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 declare abstract class OINODataSource {
+    isConnected: boolean;
+    isValidated: boolean;
+    /**
+     * 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 declare abstract class OINODataSet extends OINOResult {
+    private _data;
+    /** 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[]);
+    /**
+     * 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;
+    /**
+     * Finds the first error message that occured
+     *
+     */
+    getFirstError(): string;
+    /**
+     * Finds the last error message that occured
+     *
+     */
+    getLastError(): 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 OINOMemoryDataset extends OINODataSet {
+    private _rows;
+    private _currentRow;
+    private _eof;
+    /**
+     * 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[]);
+    /**
+     * 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;
+    /**
+     * Gets all rows of data.
+     *
+     */
+    getAllRows(): Promise<OINODataRow[]>;
+    /**
+     * Rewinds data set to the first row, returns !isEof().
+     *
+     */
+    first(): boolean;
+}

package/common/src/OINOHtmlTemplate.d.ts

@@ -1,4 +1,4 @@
-import { OINOResult, OINOHttpResult } from ".";
+import { OINOResult, OINOHttpResult } from "./OINOResult.js";
 /**
  * Class for rendering HTML from data.
  */

package/common/src/OINOModelSet.d.ts

@@ -0,0 +1,64 @@
+import { OINOContentType, OINODataCell } from "./OINOConstants.js";
+import { OINODataSet } from "./OINODataSource.js";
+import { OINODataModel } from "./OINODataModel.js";
+import { OINOQueryParams } from "./OINOQueryParams.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 OINOModelSet {
+    /** Reference to datamodel */
+    readonly datamodel: OINODataModel;
+    /** Reference to data set */
+    readonly dataset: OINODataSet;
+    /** SQL parameters */
+    readonly queryParams?: OINOQueryParams;
+    /** Collection of errors */
+    errors: string[];
+    /**
+     * Constructor for `OINOModelSet`.
+     *
+     * @param datamodel data model
+     * @param dataset data set
+     * @param queryParams SQL parameters
+     */
+    constructor(datamodel: OINODataModel, dataset: OINODataSet, queryParams?: OINOQueryParams);
+    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/common/src/OINOParser.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { Buffer } from "node:buffer";
+import { OINOContentType, OINODataRow } from "./OINOConstants.js";
+import { OINODataModel } from "./OINODataModel.js";
+/**
+ * Static factory class for easily creating things based on data
+ *
+ */
+export declare class OINOParser {
+    /**
+     * 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: OINODataModel, 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;
+}