@oino-ts/types 0.21.2 → 1.0.0

package/db-mssql/src/OINODbMsSql.d.ts

@@ -0,0 +1,116 @@
+import { OINOResult, OINODataSet, OINODataCell } from "@oino-ts/common";
+import { OINODb, OINODbApi, OINODbParams } from "@oino-ts/db";
+/**
+ * Implementation of MsSql-database.
+ *
+ */
+export declare class OINODbMsSql extends OINODb {
+    private _pool;
+    /**
+     * Constructor of `OINODbMsSql`
+     * @param params database parameters
+     */
+    constructor(params: OINODbParams);
+    private _query;
+    private _exec;
+    /**
+     * Print a table name using database specific SQL escaping.
+     *
+     * @param sqlTable name of the table
+     *
+     */
+    printTableName(sqlTable: string): string;
+    /**
+     * Print a column name with correct SQL escaping.
+     *
+     * @param sqlColumn name of the column
+     *
+     */
+    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 nativeType native type name for table column
+     *
+     */
+    printCellAsValue(cellValue: OINODataCell, nativeType: string): string;
+    /**
+     * Print a single string value as valid sql literal
+     *
+     * @param sqlString string value
+     *
+     */
+    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 nativeType native type name for table column
+     *
+     */
+    parseValueAsCell(sqlValue: OINODataCell, nativeType: string): OINODataCell;
+    /**
+     * 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;
+    /**
+     * Print SQL select statement with DB specific formatting.
+     *
+     * @param tableName - The name of the table to select from.
+     * @param columns - The columns to be selected.
+     * @param values - The values to be inserted.
+     * @param returnIdFields - the id fields to return if returnIds is true (if supported by the database)
+     *
+     */
+    printSqlInsert(tableName: string, columns: string, values: string, returnIdFields?: string[]): string;
+    /**
+     * Connect to database.
+     *
+     */
+    connect(): Promise<OINOResult>;
+    /**
+     * Validate connection to database is working.
+     *
+     */
+    validate(): Promise<OINOResult>;
+    /**
+     * Disconnect from database.
+     *
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Execute a select operation.
+     *
+     * @param sql SQL statement.
+     *
+     */
+    sqlSelect(sql: string): Promise<OINODataSet>;
+    /**
+     * Execute other sql operations.
+     *
+     * @param sql SQL statement.
+     *
+     */
+    sqlExec(sql: string): Promise<OINODataSet>;
+    private _getSchemaSql;
+    private _getValidateSql;
+    /**
+     * Initialize a data model by getting the SQL schema and populating OINODataFields of
+     * the model.
+     *
+     * @param api api which data model to initialize.
+     *
+     */
+    initializeApiDatamodel(api: OINODbApi): Promise<void>;
+}

package/db-mssql/src/index.d.ts

@@ -0,0 +1 @@
+export { OINODbMsSql } from "./OINODbMsSql.js";

package/db-postgresql/src/OINODbPostgresql.d.ts

@@ -0,0 +1,95 @@
+import { OINOResult, OINODataSet, OINODataCell } from "@oino-ts/common";
+import { OINODb, OINODbApi, OINODbParams } from "@oino-ts/db";
+/**
+ * Implementation of Postgresql-database.
+ *
+ */
+export declare class OINODbPostgresql extends OINODb {
+    private _pool;
+    /**
+     * Constructor of `OINODbPostgresql`
+     * @param params database paraneters
+     */
+    constructor(params: OINODbParams);
+    private _parseFieldLength;
+    private _query;
+    private _exec;
+    /**
+     * Print a table name using database specific SQL escaping.
+     *
+     * @param sqlTable name of the table
+     *
+     */
+    printTableName(sqlTable: string): string;
+    /**
+     * Print a column name with correct SQL escaping.
+     *
+     * @param sqlColumn name of the column
+     *
+     */
+    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 nativeType native type name for table column
+     *
+     */
+    printCellAsValue(cellValue: OINODataCell, nativeType: string): string;
+    /**
+     * Print a single string value as valid sql literal
+     *
+     * @param sqlString string value
+     *
+     */
+    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 nativeType native type name for table column
+     *
+     */
+    parseValueAsCell(sqlValue: OINODataCell, nativeType: string): OINODataCell;
+    /**
+     * Connect to database.
+     *
+     */
+    connect(): Promise<OINOResult>;
+    /**
+     * Validate connection to database is working.
+     *
+     */
+    validate(): Promise<OINOResult>;
+    /**
+     * Disconnect from database.
+     *
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Execute a select operation.
+     *
+     * @param sql SQL statement.
+     *
+     */
+    sqlSelect(sql: string): Promise<OINODataSet>;
+    /**
+     * Execute other sql operations.
+     *
+     * @param sql SQL statement.
+     *
+     */
+    sqlExec(sql: string): Promise<OINODataSet>;
+    private _getSchemaSql;
+    private _getValidateSql;
+    /**
+     * Initialize a data model by getting the SQL schema and populating OINODataFields of
+     * the model.
+     *
+     * @param api api which data model to initialize.
+     *
+     */
+    initializeApiDatamodel(api: OINODbApi): Promise<void>;
+}

package/db-postgresql/src/index.d.ts

@@ -0,0 +1 @@
+export { OINODbPostgresql } from "./OINODbPostgresql.js";

package/hashid/src/OINOHashid.d.ts

@@ -0,0 +1,42 @@
+export declare const OINOHASHID_MIN_LENGTH: number;
+export declare const OINOHASHID_MAX_LENGTH: number;
+/**
+ * Hashid implementation for OINO API:s for the purpose of making it infeasible to scan
+ * through numeric autoinc keys. It's not a solution to keeping the id secret in insecure
+ * channels, just making it hard enough to not iterate through the entire key space. Half
+ * of the the hashid length is nonce and half cryptotext, i.e. 16 char hashid 8 chars of
+ * base64 encoded nonce ~ 6 bytes or 48 bits of entropy.
+ *
+ */
+export declare class OINOHashid {
+    private _key;
+    private _iv;
+    private _domainId;
+    private _minLength;
+    private _staticIds;
+    /**
+     * Hashid constructor
+     *
+     * @param key AES128 key (32 char hex-string)
+     * @param domainId a sufficiently unique domain ID in which row-Id's are unique
+     * @param minLength minimum length of nonce and crypto
+     * @param staticIds whether hash values should remain static per row or random values
+     *
+     */
+    constructor(key: string, domainId: string, minLength?: number, staticIds?: boolean);
+    /**
+     * Encode given id value as a hashid either using random data or given seed value for nonce.
+     *
+     * @param id numeric value
+     * @param cellSeed a sufficiently unique seed for the current cell to keep hashids unique but persistent (e.g. fieldname + primarykey values)
+     *
+     */
+    encode(id: string, cellSeed?: string): string;
+    /**
+     * Decode given hashid.
+     *
+     * @param hashid value
+     *
+     */
+    decode(hashid: string): string;
+}

package/hashid/src/index.d.ts

@@ -0,0 +1 @@
+export { OINOHashid } from "./OINOHashid.js";

package/index.d.ts

@@ -1,7 +1,7 @@
-/// <reference path="db/src/index.d.ts
-/// <reference path="db-bunsqlite/src/index.d.ts
-/// <reference path="db-mariadb/src/index.d.ts
-/// <reference path="db-mssql/src/index.d.ts
-/// <reference path="db-postgresql/src/index.d.ts
-/// <reference path="hashid/src/OINOHashid.d.ts
-/// <reference path="common/src/index.d.ts
+/// <reference path="db/src/index.d.ts
+/// <reference path="db-bunsqlite/src/index.d.ts
+/// <reference path="db-mariadb/src/index.d.ts
+/// <reference path="db-mssql/src/index.d.ts
+/// <reference path="db-postgresql/src/index.d.ts
+/// <reference path="hashid/src/OINOHashid.d.ts
+/// <reference path="common/src/index.d.ts

package/nosql/src/OINONoSql.d.ts

@@ -0,0 +1,81 @@
+import { OINODataSource, OINODataCell, OINOQueryFilter } from "@oino-ts/common";
+import { OINONoSqlParams, OINONoSqlEntry } from "./OINONoSqlConstants.js";
+/**
+ * Abstract base class for NoSQL storage backends.  Subclasses implement
+ * the core CRUD operations for a specific provider (e.g. Azure Table Storage).
+ *
+ * The data model exposed by the API has a fixed set of fields:
+ *   1. `partitionKey`  – partition key (primary key component, string)
+ *   2. `rowKey`        – row key (primary key component, string)
+ *   3. `timestamp`     – last modification timestamp (datetime)
+ *   4. `etag`          – entity tag (string)
+ *   5. `properties`    – all custom entity properties as a JSON string
+ *
+ * The SQL-formatting methods inherited from `OINODataSource` are not used
+ * by nosql operations; they are implemented here as passthrough stubs.
+ */
+export declare abstract class OINONoSql extends OINODataSource {
+    protected readonly nosqlParams: OINONoSqlParams;
+    /** Table name */
+    readonly name: string;
+    /**
+     * Whether this backend can auto-generate primary key values when none are
+     * supplied in a POST request.  Defaults to `false`; override in subclasses
+     * that support server-side key generation (e.g. UUID on insert).
+     */
+    readonly supportsAutoKey: boolean;
+    /**
+     * Constructor for `OINONoSql`.
+     * @param params nosql storage connection parameters
+     */
+    constructor(params: OINONoSqlParams);
+    printTableName(name: string): string;
+    printColumnName(name: string): string;
+    printCellAsValue(cellValue: OINODataCell, nativeType: string): string;
+    printStringValue(s: string): string;
+    parseValueAsCell(v: OINODataCell, nativeType: string): OINODataCell;
+    /**
+     * Test whether a NoSQL entry matches an `OINOQueryFilter` predicate.
+     * Used for in-memory (result) filtering when the storage backend cannot
+     * translate the predicate to a native query.
+     *
+     * @param entry nosql entry to test
+     * @param filter filter predicate to evaluate
+     */
+    protected static matchesEntry(entry: OINONoSqlEntry, filter: OINOQueryFilter): boolean;
+    /**
+     * List all entities in the table, applying storage-level filtering where
+     * possible and in-memory result filtering for remaining predicates.
+     *
+     * @param filter optional query filter to apply
+     */
+    abstract listEntries(filter?: OINOQueryFilter): Promise<OINONoSqlEntry[]>;
+    /**
+     * Fetch a single entity by its primary key values.
+     *
+     * Returns `null` when no entity with the given primary key exists.
+     *
+     * @param primaryKey ordered primary key values as defined by the implementation's data model
+     */
+    abstract getEntry(primaryKey: string[]): Promise<OINONoSqlEntry | null>;
+    /**
+     * Upsert (insert or replace) an entity.
+     *
+     * @param entry entity to upsert
+     */
+    abstract upsertEntry(entry: OINONoSqlEntry): Promise<void>;
+    /**
+     * Upsert (insert or replace) multiple entities in the most efficient way
+     * the backend supports.  The default implementation loops over
+     * `upsertEntry`; override in subclasses that support native batch writes.
+     *
+     * @param entries entities to upsert
+     */
+    upsertEntries(entries: OINONoSqlEntry[]): Promise<void>;
+    /**
+     * Delete an entity.
+     *
+     * @param primaryKey ordered primary key values as defined by the implementation's data model
+     */
+    abstract deleteEntry(primaryKey: string[]): Promise<void>;
+}

package/nosql/src/OINONoSqlApi.d.ts

@@ -0,0 +1,67 @@
+import { OINOApi, OINOApiParams, OINOApiRequest, OINOApiResult, OINOContentType, OINOQueryParams, OINOHttpRequest, type OINOApiData } from "@oino-ts/common";
+import { OINONoSql } from "./OINONoSql.js";
+import { OINONoSqlDataModel } from "./OINONoSqlDataModel.js";
+/**
+ * REST API for NoSQL table storage.
+ *
+ * Supports the following HTTP methods:
+ * - **GET without id** – lists all entities and returns metadata as JSON.
+ * - **GET with id** – returns a single entity.
+ * - **POST / PUT with id** – upserts an entity; body must be a JSON object
+ *   with a `properties` key containing the custom entity properties.
+ * - **DELETE with id** – deletes the named entity.
+ *
+ * The URL row ID format uses `OINOConfig.OINO_ID_SEPARATOR` to join the
+ * primary key field values, matching the number and order of primary key
+ * fields in the data model (same `_OINOID_` convention as `OINODbApi`).
+ */
+export declare class OINONoSqlApi extends OINOApi {
+    /** NoSQL storage backend */
+    readonly noSql: OINONoSql;
+    /** NoSQL-specific data model (populated by `initializeDatamodel`) */
+    noSqlDatamodel: OINONoSqlDataModel | null;
+    /**
+     * Constructor.
+     *
+     * NOTE: `initializeDatamodel` (or `OINONoSqlFactory.createApi`) must be
+     * called before the first request is dispatched.
+     *
+     * @param noSql nosql storage backend
+     * @param params API parameters
+     */
+    constructor(noSql: OINONoSql, params: OINOApiParams);
+    /**
+     * Attach the static nosql data model and mark the API as initialised.
+     *
+     * @param datamodel `OINONoSqlDataModel` instance for this API
+     */
+    initializeDatamodel(datamodel: OINONoSqlDataModel): void;
+    /**
+     * Parse a `_OINOID_`-formatted row ID into an ordered array of decoded
+     * primary key values using `OINOConfig.parseOINOId`.  Returns `null` when
+     * the number of parts does not match the data model's primary key count.
+     *
+     * @param rowId `_OINOID_`-formatted row ID
+     */
+    private _parseRowId;
+    /**
+     * Validate a data row against API parameters.  Currently checks whether
+     * primary key fields are present when `requirePrimaryKey` is `true`.
+     *
+     * `requirePrimaryKey` is derived at the call-site from:
+     * - `this.params.failOnInsertWithoutKey` when explicitly set, or
+     * - `!this.noSql.supportsAutoKey` as the implementation-specific default.
+     */
+    private _validateRow;
+    private _parseData;
+    private _rowToEntry;
+    private _doGet;
+    private _doPut;
+    private _doPost;
+    private _doDelete;
+    doApiRequest(request: OINOApiRequest): Promise<OINOApiResult>;
+    doBatchUpdate(method: string, rowId: string, rowData: OINOApiData, queryParams?: OINOQueryParams): Promise<OINOApiResult>;
+    doBatchApiRequest(request: OINOApiRequest): Promise<OINOApiResult>;
+    doHttpRequest(request: OINOHttpRequest, rowId: string, rowData: OINOApiData, queryParams: OINOQueryParams): Promise<OINOApiResult>;
+    doRequest(method: string, rowId: string, rowData: OINOApiData, queryParams: OINOQueryParams, contentType?: OINOContentType): Promise<OINOApiResult>;
+}

package/nosql/src/OINONoSqlConstants.d.ts

@@ -0,0 +1,34 @@
+import type { OINONoSql } from "./OINONoSql.js";
+/**
+ * NoSQL class (constructor) type
+ * @param params nosql parameters
+ */
+export type OINONoSqlConstructor = new (params: OINONoSqlParams) => OINONoSql;
+/** NoSQL storage connection parameters */
+export type OINONoSqlParams = {
+    /** Name of the nosql class (e.g. OINONoSqlAzureTable) */
+    type: string;
+    /** Service endpoint URL */
+    url: string;
+    /** Table name */
+    table: string;
+    /** Provider-specific connection string (e.g. Azure Storage connection string) */
+    connectionStr?: string;
+    /**
+     * Optional static partition key.  When set, all read/write operations are
+     * automatically scoped to this partition key, allowing multiple logical
+     * tables to share a single Azure Table Storage table.
+     */
+    staticPartitionKey?: string;
+};
+/** A single NoSQL entity entry */
+export type OINONoSqlEntry = {
+    /** Primary key values in the order defined by the implementation's data model */
+    primaryKey: string[];
+    /** Last modification timestamp */
+    timestamp: Date;
+    /** Entity tag */
+    etag: string;
+    /** All custom entity properties as a key-value map */
+    properties: Record<string, unknown>;
+};

package/nosql/src/OINONoSqlDataModel.d.ts

@@ -0,0 +1,29 @@
+import { OINODataModel, OINOMemoryDataset } from "@oino-ts/common";
+import { OINONoSqlApi } from "./OINONoSqlApi.js";
+import { OINONoSqlEntry } from "./OINONoSqlConstants.js";
+/**
+ * Static data model for NoSQL entity listings.
+ *
+ * The canonical field order is determined by the implementation's
+ * `initializeApiDatamodel` call.  Primary key fields are mapped positionally
+ * to `OINONoSqlEntry.primaryKey`, while the remaining fields (`timestamp`,
+ * `etag`, `properties`) are matched by name.
+ */
+export declare class OINONoSqlDataModel extends OINODataModel {
+    /** Reference to the owning NoSQL API */
+    readonly noSqlApi: OINONoSqlApi;
+    /**
+     * Constructor.  Fields are added externally by the nosql implementation
+     * via `initializeApiDatamodel`.
+     *
+     * @param api the `OINONoSqlApi` that owns this data model
+     */
+    constructor(api: OINONoSqlApi);
+    /**
+     * Convert an array of NoSQL entries into an in-memory dataset whose
+     * columns match the fields present in this model.
+     *
+     * @param entries nosql entries from the storage backend
+     */
+    entriesToDataset(entries: OINONoSqlEntry[]): OINOMemoryDataset;
+}

package/nosql/src/OINONoSqlFactory.d.ts

@@ -0,0 +1,40 @@
+import { OINOApiParams } from "@oino-ts/common";
+import { OINONoSqlParams, OINONoSqlConstructor } from "./OINONoSqlConstants.js";
+import { OINONoSql } from "./OINONoSql.js";
+import { OINONoSqlApi } from "./OINONoSqlApi.js";
+/**
+ * Static factory for creating `OINONoSql` instances and `OINONoSqlApi` instances
+ * from registered provider classes.
+ *
+ * Usage:
+ * ```ts
+ * OINONoSqlFactory.registerNoSql("OINONoSqlAzureTable", OINONoSqlAzureTable)
+ * const nosql = await OINONoSqlFactory.createNoSql({ type: "OINONoSqlAzureTable", ... })
+ * const api   = await OINONoSqlFactory.createApi(nosql, { apiName: "entities", tableName: "myTable" })
+ * ```
+ */
+export declare class OINONoSqlFactory {
+    private static _registry;
+    /**
+     * Register a nosql provider class under the given name.
+     *
+     * @param name name used in `OINONoSqlParams.type`
+     * @param noSqlClass constructor of the provider
+     */
+    static registerNoSql(name: string, noSqlClass: OINONoSqlConstructor): void;
+    /**
+     * Create and optionally connect/validate a nosql backend from params.
+     *
+     * @param params connection parameters
+     * @param connect if true, calls `connect()` on the backend
+     * @param validate if true, calls `validate()` on the backend
+     */
+    static createNoSql(params: OINONoSqlParams, connect?: boolean, validate?: boolean): Promise<OINONoSql>;
+    /**
+     * Create an `OINONoSqlApi` and initialise its data model.
+     *
+     * @param noSql nosql backend to use
+     * @param params API parameters
+     */
+    static createApi(noSql: OINONoSql, params: OINOApiParams): Promise<OINONoSqlApi>;
+}

package/nosql/src/index.d.ts

@@ -0,0 +1,5 @@
+export { OINONoSql } from "./OINONoSql.js";
+export { OINONoSqlDataModel } from "./OINONoSqlDataModel.js";
+export { OINONoSqlFactory } from "./OINONoSqlFactory.js";
+export { OINONoSqlApi } from "./OINONoSqlApi.js";
+export { type OINONoSqlConstructor, type OINONoSqlParams, type OINONoSqlEntry } from "./OINONoSqlConstants.js";