@oino-ts/nosql 1.0.0

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

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@oino-ts/nosql",
+  "version": "1.0.0",
+  "description": "OINO TS library package for publishing NoSQL storage as a REST API.",
+  "author": "Matias Kiviniemi (pragmatta)",
+  "license": "MPL-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pragmatta/oino-ts.git"
+  },
+  "keywords": [
+    "nosql",
+    "storage",
+    "rest-api",
+    "typescript",
+    "library"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "dependencies": {
+    "@oino-ts/common": "1.0.0",
+    "oino-ts": "file:.."
+  },
+  "devDependencies": {
+    "@oino-ts/types": "1.0.0",
+    "@types/bun": "^1.1.14",
+    "@types/node": "^21.0.00",
+    "typescript": "~5.9.0"
+  },
+  "files": [
+    "src/*.ts",
+    "dist/cjs/*.js",
+    "dist/esm/*.js",
+    "dist/types/*.d.ts"
+  ]
+}

package/src/OINONoSql.ts

@@ -0,0 +1,202 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+
+import { OINODataSource, OINODataCell, OINOQueryFilter, OINOQueryBooleanOperation, OINOQueryComparison, OINOQueryNullCheck } from "@oino-ts/common"
+import { OINONoSqlParams, OINONoSqlEntry } from "./OINONoSqlConstants.js"
+
+const NOSQL_LIKE_ESCAPE_REGEX = /[.*+?^${}()|[\]\\]/g
+const NOSQL_LIKE_PERCENT_REGEX = /%/g
+const NOSQL_LIKE_UNDERSCORE_REGEX = /_/g
+
+/**
+ * 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 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 = false
+
+    /**
+     * Constructor for `OINONoSql`.
+     * @param params nosql storage connection parameters
+     */
+    constructor(params: OINONoSqlParams) {
+        super()
+        this.nosqlParams = { ...params }
+        this.name = this.nosqlParams.table
+    }
+
+    // ── OINODataSource passthrough stubs ──────────────────────────────────
+
+    printTableName(name: string): string {
+        return name
+    }
+
+    printColumnName(name: string): string {
+        return name
+    }
+
+    printCellAsValue(cellValue: OINODataCell, nativeType: string): string {
+        if (cellValue === null || cellValue === undefined) {
+            return ""
+        }
+        if (cellValue instanceof Date) {
+            return cellValue.toISOString()
+        }
+        return String(cellValue)
+    }
+
+    printStringValue(s: string): string {
+        return s
+    }
+
+    parseValueAsCell(v: OINODataCell, nativeType: string): OINODataCell {
+        if (nativeType === "DATETIME" && typeof v === "string" && v !== "") {
+            return new Date(v)
+        }
+        return v
+    }
+
+    // ── NoSQL-specific filter helpers ─────────────────────────────────────
+
+    /**
+     * 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 {
+        if (filter.isEmpty()) return true
+
+        const op = filter.operator
+
+        if (op === OINOQueryBooleanOperation.and) {
+            return OINONoSql.matchesEntry(entry, filter.leftSide as OINOQueryFilter) &&
+                   OINONoSql.matchesEntry(entry, filter.rightSide as OINOQueryFilter)
+        }
+        if (op === OINOQueryBooleanOperation.or) {
+            return OINONoSql.matchesEntry(entry, filter.leftSide as OINOQueryFilter) ||
+                   OINONoSql.matchesEntry(entry, filter.rightSide as OINOQueryFilter)
+        }
+        if (op === OINOQueryBooleanOperation.not) {
+            return !OINONoSql.matchesEntry(entry, filter.rightSide as OINOQueryFilter)
+        }
+
+        const field_name = filter.leftSide as string
+        const compare_value = filter.rightSide as string
+
+        let field_value: string | number | Date | null
+        switch (field_name) {
+            case "timestamp":    field_value = entry.timestamp; break
+            case "etag":         field_value = entry.etag; break
+            default: return true
+        }
+
+        if (op === OINOQueryNullCheck.isnull) return field_value === null
+        if (op === OINOQueryNullCheck.isNotNull) return field_value !== null
+        if (field_value === null) return false
+
+        if (field_value instanceof Date) {
+            const ms = field_value.getTime()
+            const cmp_ms = new Date(compare_value).getTime()
+            switch (op) {
+                case OINOQueryComparison.lt: return ms < cmp_ms
+                case OINOQueryComparison.le: return ms <= cmp_ms
+                case OINOQueryComparison.eq: return ms === cmp_ms
+                case OINOQueryComparison.ne: return ms !== cmp_ms
+                case OINOQueryComparison.ge: return ms >= cmp_ms
+                case OINOQueryComparison.gt: return ms > cmp_ms
+                default: return true
+            }
+        }
+
+        const str_value = String(field_value)
+        switch (op) {
+            case OINOQueryComparison.lt: return str_value < compare_value
+            case OINOQueryComparison.le: return str_value <= compare_value
+            case OINOQueryComparison.eq: return str_value === compare_value
+            case OINOQueryComparison.ne: return str_value !== compare_value
+            case OINOQueryComparison.ge: return str_value >= compare_value
+            case OINOQueryComparison.gt: return str_value > compare_value
+            case OINOQueryComparison.like: {
+                const escaped = compare_value
+                    .replace(NOSQL_LIKE_ESCAPE_REGEX, "\\$&")
+                    .replace(NOSQL_LIKE_PERCENT_REGEX, ".*")
+                    .replace(NOSQL_LIKE_UNDERSCORE_REGEX, ".")
+                return new RegExp("^" + escaped + "$", "i").test(str_value)
+            }
+            default: return true
+        }
+    }
+
+    // ── Abstract NoSQL operations ─────────────────────────────────────────
+
+    /**
+     * 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
+     */
+    async upsertEntries(entries: OINONoSqlEntry[]): Promise<void> {
+        for (const entry of entries) {
+            await this.upsertEntry(entry)
+        }
+    }
+
+    /**
+     * Delete an entity.
+     *
+     * @param primaryKey ordered primary key values as defined by the implementation's data model
+     */
+    abstract deleteEntry(primaryKey: string[]): Promise<void>
+}