@oino-ts/types 0.16.1 → 0.17.1

package/common/src/OINOBenchmark.d.ts

@@ -18,6 +18,11 @@ export declare abstract class OINOBenchmark {
      *
      */
     static setInstance(instance: OINOBenchmark): void;
+    /**
+     * Get active benchmarking instance.
+     *
+     */
+    static getInstance(): OINOBenchmark;
     protected abstract _reset(): void;
     /**
      * Reset benchmark data (but not what is enabled).

package/common/src/OINORequest.d.ts

@@ -0,0 +1,57 @@
+import { OINOContentType } from ".";
+export interface OINORequestInit {
+    params?: Record<string, string>;
+}
+/**
+ * OINO API request result object with returned data and/or http status code/message and
+ * error / warning messages.
+ *
+ */
+export declare class OINORequest {
+    /** Key-value parameters */
+    params?: Record<string, string>;
+    /**
+     * Constructor of OINORequest.
+     *
+     * @param init initialization values
+     *
+     */
+    constructor(init?: OINORequestInit);
+    /**
+     * Copy values from different result.
+     *
+     * @param request source value
+     */
+    copy(request: OINORequest): void;
+}
+export interface OINOHttpRequestInit extends OINORequestInit {
+    url?: URL;
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    requestType?: OINOContentType;
+    responseType?: OINOContentType;
+    multipartBoundary?: string;
+    lastModified?: number;
+}
+/**
+ * Specialized result for HTTP responses.
+ */
+export declare class OINOHttpRequest extends OINORequest {
+    readonly url?: URL;
+    readonly method: string;
+    readonly headers: Record<string, string>;
+    readonly body: string;
+    readonly requestType: OINOContentType;
+    readonly responseType: OINOContentType;
+    readonly multipartBoundary?: string;
+    readonly lastModified?: number;
+    readonly etags?: string[];
+    /**
+     * Constructor for a `OINOHttpRequest`
+     *
+     * @param init initialization values
+     *
+     */
+    constructor(init: OINOHttpRequestInit);
+}

package/common/src/OINOResult.d.ts

@@ -1,3 +1,9 @@
+export interface OINOResultInit {
+    success?: boolean;
+    status?: number;
+    statusText?: string;
+    messages?: string[];
+}
 /**
  * OINO API request result object with returned data and/or http status code/message and
  * error / warning messages.
@@ -7,16 +13,18 @@ export declare class OINOResult {
     /** Wheter request was successfully executed */
     success: boolean;
     /** HTTP status code */
-    statusCode: number;
+    status: number;
     /** HTTP status message */
-    statusMessage: string;
+    statusText: string;
     /** Error / warning messages */
     messages: string[];
     /**
      * Constructor of OINOResult.
      *
+     * @param init initialization values
+     *
      */
-    constructor();
+    constructor(init?: OINOResultInit);
     /**
      * Copy values from different result.
      *
@@ -31,12 +39,12 @@ export declare class OINOResult {
     /**
      * Set HTTP error status using given code and message. Returns self reference for chaining.
      *
-     * @param statusCode HTTP status code
-     * @param statusMessage HTTP status message
+     * @param status HTTP status code
+     * @param statusText HTTP status message
      * @param operation operation where error occured
      *
      */
-    setError(statusCode: number, statusMessage: string, operation: string): OINOResult;
+    setError(status: number, statusText: string, operation: string): OINOResult;
     /**
      * Add warning message. Returns self reference for chaining.
      *
@@ -77,12 +85,11 @@ export declare class OINOResult {
      *
      */
     printLog(): string;
-    /**
-     * Get a Response object from the result values.
-     *
-     * @param headers HTTP headers (overrides existing values)
-     */
-    getStatusResponse(headers?: Record<string, string>): Response;
+}
+export interface OINOHttpResultInit extends OINOResultInit {
+    body?: string;
+    expires?: number;
+    lastModified?: number;
 }
 /**
  * Specialized result for HTTP responses.
@@ -91,17 +98,19 @@ export declare class OINOHttpResult extends OINOResult {
     private _etag;
     /** HTTP body data */
     readonly body: string;
-    /** HTTP cache expiration value */
+    /** HTTP cache expiration value
+     * Note: default 0 means no expiration and 'Pragma: no-cache' is set.
+    */
     expires: number;
     /** HTTP cache last-modified value */
     lastModified: number;
     /**
      * Constructor for a `OINOHttpResult`
      *
-     * @param body HTTP body
+     * @param init initialization values
      *
      */
-    constructor(body: string);
+    constructor(init?: OINOHttpResultInit);
     /**
      * Get the ETag value for the body opportunistically, i.e. don't calculate until requested and reuse value.
      *

package/common/src/index.d.ts

@@ -1,6 +1,7 @@
 export { OINOBenchmark, OINOMemoryBenchmark } from "./OINOBenchmark.js";
 export { OINOLog, OINOLogLevel, OINOConsoleLog } from "./OINOLog.js";
-export { OINOResult, OINOHttpResult } from "./OINOResult.js";
+export { OINOResult, OINOHttpResult, type OINOResultInit, type OINOHttpResultInit } from "./OINOResult.js";
+export { OINORequest, OINOHttpRequest, type OINORequestInit, type OINOHttpRequestInit } from "./OINORequest.js";
 export { OINOStr } from "./OINOStr.js";
 export { OINOHtmlTemplate } from "./OINOHtmlTemplate.js";
 export { OINOFormatter, OINO_EMPTY_FORMATTER } from "./OINOFormatter.js";
@@ -12,6 +13,10 @@ export declare const OINO_WARNING_PREFIX = "OINO WARNING";
 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";
 /**
  * Supported content format mime-types
  */

package/db/src/OINODb.d.ts

@@ -0,0 +1,206 @@
+import { OINODbParams, OINODbApi, OINODataCell, OINODataRow, OINOResult } from "./index.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 OINODb {
+    protected _params: OINODbParams;
+    /** Name of the database */
+    readonly name: string;
+    isConnected: boolean;
+    isValidated: boolean;
+    /**
+     * Constructor for `OINODb`.
+     * @param params database parameters
+     */
+    constructor(params: OINODbParams);
+    /**
+     * Connect to database.
+     *
+     */
+    abstract connect(): Promise<OINOResult>;
+    /**
+     * Validate connection to database is working.
+     *
+     */
+    abstract validate(): Promise<OINOResult>;
+    /**
+     * 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;
+}
+/**
+ * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Gets all rows of data.
+     *
+     */
+    getAllRows(): Promise<OINODataRow[]>;
+    /**
+     * Rewinds data set to the first row, returns !isEof().
+     *
+     */
+    first(): boolean;
+}

package/db/src/OINODbApi.d.ts

@@ -0,0 +1,153 @@
+import { OINODbApiParams, OINODb, OINODbDataModel, OINODataRow, OINODbModelSet, OINOHttpResult, OINOHtmlTemplate, OINODbSqlParams, OINODbSqlAggregate, OINODbSqlSelect, OINODbSqlFilter, OINODbSqlOrder, OINODbSqlLimit } from "./index.js";
+import { OINOResult, OINOHttpRequest, OINOHttpRequestInit } from "@oino-ts/common";
+import { OINOHashid } from "@oino-ts/hashid";
+export interface OINODbApiRequestInit extends OINOHttpRequestInit {
+    rowId?: string;
+    data?: string | OINODataRow[] | Buffer | Uint8Array | object | null;
+    sqlParams?: OINODbSqlParams;
+    filter?: OINODbSqlFilter;
+    order?: OINODbSqlOrder;
+    limit?: OINODbSqlLimit;
+    aggregate?: OINODbSqlAggregate;
+    select?: OINODbSqlSelect;
+}
+export declare class OINODbApiRequest extends OINOHttpRequest {
+    readonly rowId: string;
+    readonly data: string | OINODataRow[] | Buffer | Uint8Array | object | null;
+    readonly sqlParams: OINODbSqlParams;
+    constructor(init: OINODbApiRequestInit);
+}
+/**
+ * OINO API request result object with returned data and/or http status code/message and
+ * error / warning messages.
+ *
+ */
+export declare class OINODbApiResult extends OINOResult {
+    /** DbApi request params */
+    request: OINODbApiRequest;
+    /** Returned data if any */
+    data?: OINODbModelSet;
+    /**
+     * Constructor of OINODbApiResult.
+     *
+     * @param request DbApi request parameters
+     * @param data result data
+     *
+     */
+    constructor(request: OINODbApiRequest, data?: OINODbModelSet);
+    /**
+     * Creates a HTTP Response from API results.
+     *
+     * @param headers Headers to include in the response
+     *
+     */
+    writeApiResponse(headers?: Record<string, string>): Promise<Response>;
+}
+/**
+ * Specialized HTML template that can render ´OINODbApiResult´.
+ *
+ */
+export declare class OINODbHtmlTemplate extends OINOHtmlTemplate {
+    /** Locale validation regex */
+    static LOCALE_REGEX: RegExp;
+    /** Locale formatter */
+    protected _locale: Intl.DateTimeFormat | null;
+    protected _numberDecimals: number;
+    /**
+     * Constructor of OINODbHtmlTemplate.
+     *
+     * @param template HTML template string
+     * @param numberDecimals Number of decimals to use for numbers, -1 for no formatting
+     * @param dateLocaleStr Datetime format string, either "iso" for ISO8601 or "default" for system default or valid locale string
+     * @param dateLocaleStyle Datetime format style, either "short/medium/long/full" or Intl.DateTimeFormat options
+     *
+     */
+    constructor(template: string, numberDecimals?: number, dateLocaleStr?: string, dateLocaleStyle?: string | any);
+    /**
+     * Creates HTML Response from API modelset.
+     *
+     * @param modelset OINO API dataset
+     * @param overrideValues values to override in the data
+     *
+     */
+    renderFromDbData(modelset: OINODbModelSet, overrideValues?: any): Promise<OINOHttpResult>;
+}
+/**
+ * API class with method to process HTTP REST requests.
+ *
+ */
+export declare class OINODbApi {
+    /** Enable debug output on errors */
+    private _debugOnError;
+    /** API database reference */
+    readonly db: OINODb;
+    /** API datamodel */
+    readonly datamodel: OINODbDataModel;
+    /** API parameters */
+    readonly params: OINODbApiParams;
+    /** API hashid */
+    readonly hashid: OINOHashid | null;
+    /**
+     * Constructor of API object.
+     * NOTE! OINODb.initDatamodel must be called if created manually instead of the factory.
+     *
+     * @param db database for the API
+     * @param params parameters for the API
+     *
+     */
+    constructor(db: OINODb, params: OINODbApiParams);
+    private _validateRow;
+    private _parseData;
+    private _doGet;
+    private _doPost;
+    private _doPut;
+    private _doDelete;
+    /**
+     * Enable or disable debug output on errors.
+     *
+     * @param debugOnError true to enable debug output on errors, false to disable
+     */
+    setDebugOnError(debugOnError: boolean): void;
+    /**
+     * Method for handling a HTTP REST request with GET, POST, PUT, DELETE corresponding to
+     * SQL select, insert, update and delete.
+     *
+     * @param method HTTP method of the REST request
+     * @param rowId URL id of the REST request
+     * @param data HTTP body data as either serialized string or unserialized JS object or OINODataRow-array or Buffer/Uint8Array binary data
+     * @param sqlParams SQL parameters for the REST request
+     *
+     */
+    doRequest(method: string, rowId: string, data: string | OINODataRow[] | Buffer | Uint8Array | object | null, sqlParams: OINODbSqlParams): Promise<OINODbApiResult>;
+    /**
+     * Method for handling a HTTP REST request with GET, POST, PUT, DELETE corresponding to
+     * SQL select, insert, update and delete.
+     *
+     * @param request OINO DB API request
+     *
+     */
+    runRequest(request: OINODbApiRequest): Promise<OINODbApiResult>;
+    /**
+     * Method for handling a HTTP REST request with batch update using PUT or DELETE methods.
+     *
+     * @param method HTTP method of the REST request
+     * @param rowId URL id of the REST request
+     * @param data HTTP body data as either serialized string or unserialized JS object or OINODataRow-array or Buffer/Uint8Array binary data
+     *
+     */
+    doBatchUpdate(method: string, rowId: string, data: string | OINODataRow[] | Buffer | Uint8Array | object | null, sqlParams?: OINODbSqlParams): Promise<OINODbApiResult>;
+    /**
+     * Method for handling a HTTP REST request with batch update using PUT or DELETE methods.
+     *
+     * @param request HTTP URL parameters as key-value-pairs
+     *
+     */
+    runBatchUpdate(request: OINODbApiRequest): Promise<OINODbApiResult>;
+    /**
+     * Method to check if a field is included in the API params.
+     *
+     * @param fieldName name of the field
+     *
+     */
+    isFieldIncluded(fieldName: string): boolean;
+}

package/db/src/OINODbConfig.d.ts

@@ -0,0 +1,56 @@
+/** Set the name of the OINO ID field (default \_OINOID\_) */
+export declare class OINODbConfig {
+    /** Name of the synthetic OINO ID field */
+    static OINODB_ID_FIELD: string;
+    /** Private key separator of the synthetic OINO ID field */
+    static OINODB_ID_SEPARATOR: string;
+    private static OINODB_ID_SEPARATOR_ESCAPED;
+    /** Name of the OINODbSqlFilter-parameter in request */
+    static OINODB_SQL_FILTER_PARAM: string;
+    /** Name of the OINODbSqlOrder-parameter in request */
+    static OINODB_SQL_ORDER_PARAM: string;
+    /** Name of the OINODbSqlLimit-parameter in request */
+    static OINODB_SQL_LIMIT_PARAM: string;
+    /** Name of the OINODbSqlAggregate-parameter in request */
+    static OINODB_SQL_AGGREGATE_PARAM: string;
+    /** Name of the OINODbSqlSelect-parameter in request */
+    static OINODB_SQL_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;
+    /**
+     * Set the name of the OINODbSqlFilter-param field
+     *
+     * @param sqlFilterParam name of the http parameter with `OINODbSqlFilter` definition
+     *
+     */
+    static setOinoSqlFilterParam(sqlFilterParam: string): void;
+    /**
+     * Set the name of the OINODbSqlOrder-param field
+     *
+     * @param sqlOrderParam name of the http parameter with `OINODbSqlOrder` definition
+     *
+     */
+    static setOinoSqlOrderParam(sqlOrderParam: string): void;
+    /**
+     * Set the name of the OINODbSqlLimit-param field
+     *
+     * @param sqlLimitParam name of the http parameter with `OINODbSqlLimit` definition
+     *
+     */
+    static setOinoSqlLimitParam(sqlLimitParam: string): void;
+}