@oino-ts/common 0.21.2 → 1.0.0

package/dist/types/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/dist/types/OINOHtmlTemplate.d.ts

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

package/dist/types/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/dist/types/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;
+}

package/dist/types/OINOQueryParams.d.ts

@@ -0,0 +1,270 @@
+/**
+ * Supported logical conjunctions in filter predicates.
+ * @enum
+ */
+export declare enum OINOQueryBooleanOperation {
+    and = "and",
+    or = "or",
+    not = "not"
+}
+/**
+ * Supported logical conjunctions in filter predicates.
+ * @enum
+ */
+export declare enum OINOQueryComparison {
+    lt = "lt",
+    le = "le",
+    eq = "eq",
+    ne = "ne",
+    ge = "ge",
+    gt = "gt",
+    like = "like"
+}
+/**
+ * Supported logical conjunctions in filter predicates.
+ * @enum
+ */
+export declare enum OINOQueryNullCheck {
+    isnull = "isnull",
+    isNotNull = "isNotNull"
+}
+/**
+ * Supported aggregation functions in OINODbQueryAggregate.
+ * @enum
+ */
+export declare enum OINOQueryAggregateFunctions {
+    count = "count",
+    sum = "sum",
+    avg = "avg",
+    min = "min",
+    max = "max"
+}
+/**
+ * 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 OINOQueryFilter {
+    protected static _booleanOperationRegex: RegExp;
+    protected static _negationRegex: RegExp;
+    protected static _filterComparisonRegex: RegExp;
+    protected static _filterNullCheckRegex: RegExp;
+    readonly leftSide: OINOQueryFilter | string;
+    readonly rightSide: OINOQueryFilter | string;
+    readonly operator: OINOQueryComparison | OINOQueryBooleanOperation | OINOQueryNullCheck | null;
+    /**
+     * Constructor of `OINOQueryFilter`
+     * @param leftSide left side of the filter, either another filter or a column name
+     * @param operation operation of the filter, either `OINOQueryComparison` or `OINOQueryBooleanOperation`
+     * @param rightSide right side of the filter, either another filter or a value
+     */
+    constructor(leftSide: OINOQueryFilter | string, operation: OINOQueryComparison | OINOQueryBooleanOperation | OINOQueryNullCheck | null, rightSide: OINOQueryFilter | string);
+    /**
+     * Constructor for `OINOQueryFilter` as parser of http parameter.
+     *
+     * Supports three types of statements:
+     * - comparison: (field)-lt|le|eq|ge|gt|like(value)
+     * - negation: -not(filter)
+     * - conjunction/disjunction: (filter)-and|or(filter)
+     * - null check: -isnull(field) or -isNotNull(field)
+     *
+     * @param filterString string representation of filter from HTTP-request
+     *
+     */
+    static parse(filterString: string): OINOQueryFilter;
+    /**
+     * Construct a new `OINOQueryFilter` as combination of (boolean and/or) of two filters.
+     *
+     * @param leftSide left side to combine
+     * @param operation boolean operation to use in combination
+     * @param rightSide right side to combine
+     *
+     */
+    static combine(leftSide: OINOQueryFilter | undefined, operation: OINOQueryBooleanOperation, rightSide: OINOQueryFilter | undefined): OINOQueryFilter | undefined;
+    /**
+     * Combine two filters with an AND operation.
+     *
+     * @param leftSide left side filter
+     * @param rightSide right side filter
+     *
+     */
+    static and(leftSide: OINOQueryFilter, rightSide: OINOQueryFilter): OINOQueryFilter | undefined;
+    /**
+     * Combine two filters with an OR operation.
+     *
+     * @param leftSide left side filter
+     * @param rightSide right side filter
+     *
+     */
+    static or(leftSide: OINOQueryFilter, rightSide: OINOQueryFilter): OINOQueryFilter | undefined;
+    /**
+     * Negate a filter with a NOT operation.
+     *
+     * @param leftSide left side filter
+     *
+     */
+    static not(leftSide: OINOQueryFilter): OINOQueryFilter | undefined;
+    /**
+     * Does filter contain any valid conditions.
+     *
+     */
+    isEmpty(): boolean;
+}
+/**
+ * Class for ordering select results on a number of columns.
+ *
+ */
+export declare class OINOQueryOrder {
+    protected static _orderColumnRegex: RegExp;
+    readonly columns: string[];
+    readonly descending: boolean[];
+    /**
+     * Constructor for `OINOQueryOrder`.
+     *
+     * @param column_or_array single or array of columns to order on
+     * @param descending_or_array single or array of booleans if ordes is descending
+     *
+     */
+    constructor(column_or_array: string[] | string, descending_or_array: boolean[] | boolean);
+    /**
+     * Constructor for `OINOQueryOrder` as parser of http parameter.
+     *
+     * Supports comma separated list of column orders formatted as :
+     * - `column` - order by column in ascending order
+     * - `column ASC|DESC` - order by single either ascending or descending order
+     * - `column+|-` - order by single either ascending or descending order
+     *
+     * @param orderString string representation of order from HTTP-request
+     *
+     */
+    static parse(orderString: string): OINOQueryOrder;
+    /**
+     * Does filter contain any valid conditions.
+     *
+     */
+    isEmpty(): boolean;
+}
+/**
+ * Class for limiting the number of results.
+ *
+ */
+export declare class OINOQueryLimit {
+    protected static _limitRegex: RegExp;
+    readonly limit: number;
+    readonly page: number;
+    /**
+     * Constructor for `OINOQueryLimit`.
+     *
+     * @param limit maximum number of items to return
+     * @param page page number to return starting from 1
+     *
+     */
+    constructor(limit: number, page?: number);
+    /**
+     * Constructor for `OINOQueryLimit` as parser of http parameter.
+     *
+     * Supports limit and page formatted as:
+     * - `limit` - limit number of items to return
+     * - `limit page n` - limit number of items to return and return page n (starting from 1)
+     * - `limit.n` - limit number of items to return and return page n (starting from 1)
+     *
+     * @param limitString string representation of limit from HTTP-request
+     *
+     */
+    static parse(limitString: string): OINOQueryLimit;
+    /**
+     * Does filter contain any valid conditions.
+     *
+     */
+    isEmpty(): boolean;
+}
+/**
+ * Class for limiting the number of results.
+ *
+ */
+export declare class OINOQueryAggregate {
+    protected static _aggregateRegex: RegExp;
+    readonly functions: OINOQueryAggregateFunctions[];
+    readonly fields: string[];
+    /**
+     * Constructor for `OINOQueryAggregate`.
+     *
+     * @param functions aggregate function to use
+     * @param fields fields to aggregate
+     *
+     */
+    constructor(functions: OINOQueryAggregateFunctions[], fields: string[]);
+    /**
+     * Constructor for `OINOQueryAggregate` as parser of http parameter.
+     *
+     * Supports comma separated list of aggregates formatted as:
+     * - `function(field)`
+     *
+     * Supported functions are count, sum, avg, min, max.
+     *
+     * @param aggregatorString string representation of limit from HTTP-request
+     *
+     */
+    static parse(aggregatorString: string): OINOQueryAggregate;
+    /**
+     * Does filter contain any valid conditions.
+     *
+     */
+    isEmpty(): boolean;
+    /**
+     * Does filter contain any valid conditions.
+     *
+     * @param field field to check if it is aggregated
+     */
+    isAggregated(field: string): boolean;
+}
+/**
+ * Class for ordering select results on a number of columns.
+ *
+ */
+export declare class OINOQuerySelect {
+    readonly columns: string[];
+    /**
+     * Constructor for `OINOQuerySelect`.
+     *
+     * @param columns array of columns to select
+     *
+     */
+    constructor(columns: string[]);
+    /**
+     * Constructor for `OINOQuerySelect` as parser of http parameter.
+     *
+     * @param columns comma separated string selected columns from HTTP-request
+     *
+     */
+    static parse(columns: string): OINOQuerySelect;
+    /**
+     * Does select contain any valid columns.
+     *
+     */
+    isEmpty(): boolean;
+    /**
+     * Does select include given column.
+     *
+     * @param field field to check if it is selected
+     *
+     */
+    isSelected(field: string): boolean;
+}
+/** Request options */
+export type OINOQueryParams = {
+    /** Additional SQL select where-conditions */
+    filter?: OINOQueryFilter;
+    /** SQL result ordering conditions */
+    order?: OINOQueryOrder;
+    /** SQL result limit condition */
+    limit?: OINOQueryLimit;
+    /** SQL aggregation functions */
+    aggregate?: OINOQueryAggregate;
+    /** SQL select condition */
+    select?: OINOQuerySelect;
+};

package/dist/types/OINORequest.d.ts

@@ -1,7 +1,8 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import { Buffer } from "node:buffer";
-import { OINOContentType, OINOHeaders, OINOHeadersInit } from ".";
+import { OINOContentType } from "./OINOConstants.js";
+import { OINOHeaders, type OINOHeadersInit } from "./OINOHeaders.js";
 export interface OINORequestInit {
     params?: Record<string, string>;
 }
@@ -29,6 +30,7 @@ export interface OINOHttpRequestInit extends OINORequestInit {
     body?: OINOHttpData;
     requestType?: OINOContentType;
     responseType?: OINOContentType;
+    responseDownload?: string;
     multipartBoundary?: string;
     lastModified?: number;
 }
@@ -42,6 +44,7 @@ export declare class OINOHttpRequest extends OINORequest {
     body: OINOHttpData;
     requestType: OINOContentType;
     responseType: OINOContentType;
+    responseDownload?: string;
     multipartBoundary?: string;
     lastModified?: number;
     etags?: string[];

package/dist/types/OINOResult.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
 /// <reference types="node" />
 import { Buffer } from "node:buffer";
-import { OINOHeaders, OINOHeadersInit } from ".";
+import { OINOHeaders, type OINOHeadersInit } from "./OINOHeaders.js";
 export interface OINOResultInit {
     success?: boolean;
     status?: number;

package/dist/types/OINOStr.d.ts

@@ -1,4 +1,4 @@
-import { OINOContentType } from ".";
+import { OINOContentType } from "./OINOConstants.js";
 /** Callback to filter data fields */
 export type OINOStrEncoder = (str: string) => string;
 /**

package/dist/types/OINOSwagger.d.ts

@@ -0,0 +1,25 @@
+import { OINOApi } from "./OINOApi.js";
+/**
+ * Static class for Swagger utilities
+ *
+ */
+export declare class OINOSwagger {
+    private static _getSchemaApiMethodParamsQueryId;
+    private static _getSchemaApiMethodParamsBody;
+    private static _getSchemaApiMethodDescription;
+    private static _getSchemaApiMethodOperationId;
+    private static _getSchemaOinoResponse;
+    private static _getSchemaFieldType;
+    private static _getSwaggerApiType;
+    private static _getSchemaType;
+    private static _getSchemaApiMethodParams;
+    private static _getSchemaApiMethod;
+    private static _getSwaggerApiPath;
+    /**
+     * Returns swagger.json as object of the given API's.
+     *
+     * @param apis array of API's use for Swagger definition
+     *
+     */
+    static getApiDefinition(apis: OINOApi[]): any;
+}

package/dist/types/index.d.ts

@@ -1,35 +1,18 @@
+export { OINOApi, OINOApiRequest, OINOApiResult, OINOApiHtmlTemplate, type OINOApiParams, type OINOApiData, type OINOApiRequestInit } from "./OINOApi.js";
 export { OINOBenchmark, OINOMemoryBenchmark } from "./OINOBenchmark.js";
+export { OINOConfig } from "./OINOConfig.js";
+export { OINO_ERROR_PREFIX, OINO_WARNING_PREFIX, OINO_INFO_PREFIX, OINO_DEBUG_PREFIX, OINO_REQUEST_TYPE_PARAM, OINO_RESPONSE_TYPE_PARAM, OINOContentType, type OINODataFieldParams, type OINODataCell, type OINODataRow, OINO_EMPTY_ROW, OINO_EMPTY_ROWS } from "./OINOConstants.js";
+export { OINODataModel } from "./OINODataModel.js";
+export { OINODataSource, OINODataSet, OINOMemoryDataset } from "./OINODataSource.js";
+export { OINODataField, OINOStringDataField, OINONumberDataField, OINOBooleanDataField, OINODatetimeDataField, OINOBlobDataField, type OINODataFieldFilter } from "./OINODataField.js";
+export { OINOFormatter, OINO_EMPTY_FORMATTER } from "./OINOFormatter.js";
+export { OINOHeaders, type OINOHeadersInit } from "./OINOHeaders.js";
+export { OINOHtmlTemplate } from "./OINOHtmlTemplate.js";
 export { OINOLog, OINOLogLevel, OINOConsoleLog } from "./OINOLog.js";
-export { OINOResult, OINOHttpResult, type OINOResultInit, type OINOHttpResultInit } from "./OINOResult.js";
+export { OINOModelSet } from "./OINOModelSet.js";
+export { OINOParser } from "./OINOParser.js";
+export { OINOQueryBooleanOperation, OINOQueryComparison, OINOQueryNullCheck, OINOQueryAggregateFunctions, OINOQuerySelect, OINOQueryFilter, OINOQueryOrder, OINOQueryLimit, OINOQueryAggregate, type OINOQueryParams } from "./OINOQueryParams.js";
 export { OINORequest, OINOHttpRequest, type OINOHttpData, type OINORequestInit, type OINOHttpRequestInit } from "./OINORequest.js";
+export { OINOResult, OINOHttpResult, type OINOResultInit, type OINOHttpResultInit } from "./OINOResult.js";
 export { OINOStr } from "./OINOStr.js";
-export { OINOHtmlTemplate } from "./OINOHtmlTemplate.js";
-export { OINOFormatter, OINO_EMPTY_FORMATTER } from "./OINOFormatter.js";
-export { OINOHeaders, type OINOHeadersInit } from "./OINOHeaders.js";
-/** 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";
-/**
- * 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"
-}
+export { OINOSwagger } from "./OINOSwagger.js";