@oino-ts/db 0.0.11

package/dist/types/OINODbDataModel.d.ts

@@ -0,0 +1,108 @@
+import { OINODbDataField, OINODbApi, OINODataRow, OINODbDataFieldFilter, OINODbSqlParams } from "./index.js";
+/**
+ * OINO Datamodel object for representing one database table and it's columns.
+ *
+ */
+export declare class OINODbDataModel {
+    private _columnLookup;
+    /** Database refererence of the table */
+    readonly api: OINODbApi;
+    /** Field refererences of the API */
+    readonly fields: OINODbDataField[];
+    /**
+     * 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);
+    /**
+     * Initialize datamodel from SQL schema.
+     *
+     */
+    initialize(): Promise<void>;
+    private _printSqlColumnNames;
+    private _printSqlInsertColumnsAndValues;
+    private _printSqlUpdateValues;
+    private _printSqlPrimaryKeyCondition;
+    /**
+     * Add a field to the datamodel.
+     *
+     * @param field dataset field
+     *
+     */
+    addField(field: OINODbDataField): void;
+    /**
+     * Find a field of a given name if any.
+     *
+     * @param name name of the field to find
+     *
+     */
+    findFieldByName(name: string): OINODbDataField | 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: OINODbDataFieldFilter): OINODbDataField[];
+    /**
+     * 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[];
+    /**
+     * 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;
+    /**
+     * 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: OINODbSqlParams): 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/dist/types/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;
+    /**
+     * Moves dataset to the next row, returns !isEof().
+     *
+     */
+    abstract next(): 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;
+    /**
+     * Moves dataset to the next row, returns !isEof().
+     *
+     */
+    next(): boolean;
+    /**
+     * Gets current row of data.
+     *
+     */
+    getRow(): OINODataRow;
+    /**
+     * Rewinds data set to the first row, returns !isEof().
+     *
+     */
+    first(): boolean;
+}

package/dist/types/OINODbFactory.d.ts

@@ -0,0 +1,99 @@
+import { OINODbApi, OINODbApiParams, OINODbParams, OINODbDataModel, OINODb, OINODataRow, OINODbConstructor, OINORequestParams, OINODbApiResult, OINODbModelSet } from "./index.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
+     */
+    static createDb(params: OINODbParams): 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: OINODbApiParams): Promise<OINODbApi>;
+    /**
+     * Creates a key-value-collection from Javascript URL parameters.
+     *
+     * @param request HTTP Request
+     */
+    static createParamsFromRequest(request: Request): OINORequestParams;
+    /**
+     * Creates a HTTP Response from API results.
+     *
+     * @param apiResult API results
+     * @param requestParams API request parameters
+     * @param responseHeaders Headers to include in the response
+     *
+     */
+    static createResponseFromApiResult(apiResult: OINODbApiResult, requestParams: OINORequestParams, responseHeaders?: Record<string, string>): Response;
+    /**
+     * Creates HTML Response from API modelset.
+     *
+     * @param modelset OINO API dataset
+     * @param template HTML template
+     *
+     */
+    static createHtmlFromData(modelset: OINODbModelSet, template: string): string;
+    /**
+     * Creates HTML Response from a row id.
+     *
+     * @param oinoId OINO id
+     * @param template HTML template
+     *
+     */
+    static createHtmlFromOinoId(oinoId: string, template: string): string;
+    /**
+     * Creates HTML Response from object properties.
+     *
+     * @param object object
+     * @param template HTML template
+     *
+     */
+    static createHtmlFromObject(object: any, template: string): string;
+    /**
+     * Creates HTML Response from API result.
+     *
+     * @param apiResult object
+     * @param template HTML template
+     * @param includeErrorMessages include debug messages in result
+     * @param includeWarningMessages include debug messages in result
+     * @param includeInfoMessages include debug messages in result
+     * @param includeDebugMessages include debug messages in result
+     *
+     */
+    static createHtmlFromApiResult(apiResult: OINODbApiResult, template: string, includeErrorMessages?: boolean, includeWarningMessages?: boolean, includeInfoMessages?: boolean, includeDebugMessages?: boolean): string;
+    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;
+    /**
+      * Create data rows from request body based on the datamodel.
+      *
+      * @param datamodel datamodel of the api
+      * @param data data as a string
+      * @param requestParams parameters
+      *
+      */
+    static createRows(datamodel: OINODbDataModel, data: string, requestParams: OINORequestParams): OINODataRow[];
+}

package/dist/types/OINODbModelSet.d.ts

@@ -0,0 +1,50 @@
+import { OINODbDataSet, OINODbDataModel, OINOContentType, OINODataCell } 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;
+    /** Collection of errors */
+    errors: string[];
+    /**
+     * Constructor for `OINODbModelSet`.
+     *
+     * @param datamodel data model
+     * @param dataset data set
+     */
+    constructor(datamodel: OINODbDataModel, dataset: OINODbDataSet);
+    private _encodeAndHashFieldValue;
+    private _writeRowJson;
+    private _writeStringJson;
+    private _writeHeaderCsv;
+    private _writeRowCsv;
+    private _writeStringCsv;
+    private _writeRowFormdataParameterBlock;
+    private _writeRowFormdataFileBlock;
+    private _writeRowFormdata;
+    private _writeStringFormdata;
+    private _writeRowUrlencode;
+    private _writeStringUrlencode;
+    /**
+     * Serialize model set in the given format.
+     *
+     * @param [contentType=OINOContentType.json] serialization content type
+     *
+     */
+    writeString(contentType?: OINOContentType): 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
+     *
+     */
+    getValueByFieldName(fieldName: string): OINODataCell;
+}

package/dist/types/OINODbRequestParams.d.ts

@@ -0,0 +1,130 @@
+import { OINODbDataModel } from "./index.js";
+/**
+ * Supported logical conjunctions in filter predicates.
+ * @enum
+ */
+export declare enum OINODbSqlBooleanOperation {
+    and = "and",
+    or = "or",
+    not = "not"
+}
+/**
+ * Supported logical conjunctions in filter predicates.
+ * @enum
+ */
+export declare enum OINODbSqlComparison {
+    lt = "lt",
+    le = "le",
+    eq = "eq",
+    ge = "ge",
+    gt = "gt",
+    like = "like"
+}
+/**
+ * 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 OINODbSqlFilter {
+    private static _booleanOperationRegex;
+    private static _negationRegex;
+    private static _filterComparisonRegex;
+    private _leftSide;
+    private _rightSide;
+    private _operator;
+    /**
+     * Constructor of `OINODbSqlFilter`
+     * @param leftSide left side of the filter, either another filter or a column name
+     * @param operation operation of the filter, either `OINODbSqlComparison` or `OINODbSqlBooleanOperation`
+     * @param rightSide right side of the filter, either another filter or a value
+     */
+    constructor(leftSide: OINODbSqlFilter | string, operation: OINODbSqlComparison | OINODbSqlBooleanOperation | null, rightSide: OINODbSqlFilter | string);
+    /**
+     * Constructor for `OINOFilter` as parser of http parameter.
+     *
+     * @param filterString string representation of filter from HTTP-request
+     *
+     */
+    static parse(filterString: string): OINODbSqlFilter;
+    /**
+     * Construct a new `OINOFilter` 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: OINODbSqlFilter | undefined, operation: OINODbSqlBooleanOperation, rightSide: OINODbSqlFilter | undefined): OINODbSqlFilter | undefined;
+    private _operatorToSql;
+    /**
+     * Does filter contain any valid conditions.
+     *
+     */
+    isEmpty(): boolean;
+    /**
+     * Print filter as SQL condition based on the datamodel of the API.
+     *
+     * @param dataModel data model (and database) to use for formatting of values
+     *
+     */
+    toSql(dataModel: OINODbDataModel): string;
+}
+/**
+ * Class for ordering select results on a number of columns.
+ *
+ */
+export declare class OINODbSqlOrder {
+    private static _orderColumnRegex;
+    private _columns;
+    private _directions;
+    /**
+     * Constructor for `OINODbSqlOrder`.
+     *
+     * @param orderString string representation of filter from HTTP-request
+     *
+     */
+    constructor(orderString: string);
+    /**
+     * Does filter contain any valid conditions.
+     *
+     */
+    isEmpty(): boolean;
+    /**
+     * Print order as SQL condition based on the datamodel of the API.
+     *
+     * @param dataModel data model (and database) to use for formatting of values
+     *
+     */
+    toSql(dataModel: OINODbDataModel): string;
+}
+/**
+ * Class for limiting the number of results.
+ *
+ */
+export declare class OINODbSqlLimit {
+    private static _orderColumnRegex;
+    private _limit;
+    /**
+     * Constructor for `OINODbSqlLimit`.
+     *
+     * @param limitString string representation of filter from HTTP-request
+     *
+     */
+    constructor(limitString: string);
+    /**
+     * Does filter contain any valid conditions.
+     *
+     */
+    isEmpty(): boolean;
+    /**
+     * Print order as SQL condition based on the datamodel of the API.
+     *
+     * @param dataModel data model (and database) to use for formatting of values
+     *
+     */
+    toSql(dataModel: OINODbDataModel): string;
+}

package/dist/types/OINODbSwagger.d.ts

@@ -0,0 +1,25 @@
+import { OINODbApi } from "./index.js";
+/**
+ * Static class for Swagger utilities
+ *
+ */
+export declare class OINODbSwagger {
+    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: OINODbApi[]): any;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,103 @@
+import { OINOContentType } from "@oino-ts/types";
+export { OINOContentType };
+export { OINO_ERROR_PREFIX, OINO_WARNING_PREFIX, OINO_INFO_PREFIX, OINO_DEBUG_PREFIX, OINOStr, OINOBenchmark, OINOLog, OINOLogLevel, OINOConsoleLog, OINOResult } from "@oino-ts/types";
+import { OINODb } from "./OINODb.js";
+import { OINODbDataField } from "./OINODbDataField.js";
+import { OINODbSqlFilter, OINODbSqlLimit, OINODbSqlOrder } from "./OINODbRequestParams.js";
+export { OINODbApiResult, OINODbApi } from "./OINODbApi.js";
+export { OINODbDataModel } from "./OINODbDataModel.js";
+export { OINODbModelSet } from "./OINODbModelSet.js";
+export { OINODbDataField, OINOBooleanDataField, OINONumberDataField, OINOStringDataField, OINOBlobDataField, OINODatetimeDataField } from "./OINODbDataField.js";
+export { OINODb } from "./OINODb.js";
+export { OINODbDataSet, OINODbMemoryDataSet } from "./OINODbDataSet.js";
+export { OINODbSqlFilter, OINODbSqlOrder, OINODbSqlComparison, OINODbSqlLimit, OINODbSqlBooleanOperation } from "./OINODbRequestParams.js";
+export { OINODbConfig } from "./OINODbConfig.js";
+export { OINODbFactory } from "./OINODbFactory.js";
+export { OINODbSwagger } from "./OINODbSwagger.js";
+/** API parameters */
+export type OINODbApiParams = {
+    /** 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;
+    /** Treat date type fields as just strings and use the native formatting instead of the ISO 8601 format */
+    useDatesAsString?: Boolean;
+    /** Exclude all fields with this prefix from the API */
+    excludeFieldPrefix?: string;
+    /** Exclude given fields from the API */
+    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 */
+    hashidRandomIds?: 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 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;
+};
+/** Request options */
+export type OINORequestParams = {
+    /** Content type of the request body */
+    requestType?: OINOContentType;
+    /** Content type of the response body */
+    responseType?: OINOContentType;
+    /** Multipart boundary token */
+    multipartBoundary?: string;
+    /** SQL parameters */
+    sqlParams: OINODbSqlParams;
+};
+/** 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[];
+/** Key-value collection */
+export type OINOValues = Record<string, string>;

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@oino-ts/db",
+  "version": "0.0.11",
+  "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": {
+    "@types/node": "^20.14.10",
+    "@oino-ts/types": "0.0.11"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typedoc": "^0.25.13"
+  },
+  "files": [
+    "src/*.ts",
+    "dist/cjs/*.js",
+    "dist/esm/*.js",
+    "dist/types/*.d.ts"
+  ]
+}