@oino-ts/blob 1.0.0

package/dist/cjs/OINOBlob.js

@@ -0,0 +1,194 @@
+"use strict";
+/*
+ * 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/.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OINOBlob = void 0;
+const common_1 = require("@oino-ts/common");
+const BLOB_LIKE_ESCAPE_REGEX = /[.*+?^${}()|[\]\\]/g;
+const BLOB_LIKE_PERCENT_REGEX = /%/g;
+const BLOB_LIKE_UNDERSCORE_REGEX = /_/g;
+/**
+ * Abstract base class for blob storage backends.  Subclasses implement
+ * the two core operations (`listEntries` and `fetchEntry`) for a specific
+ * provider (e.g. Azure Blob Storage, S3, …).
+ *
+ * The SQL-formatting methods inherited from `OINODataSource` are not used
+ * by blob operations; they are implemented here as passthrough stubs so
+ * that the blob datasource can still be composed with `OINODataField`.
+ */
+class OINOBlob extends common_1.OINODataSource {
+    blobParams;
+    /** Container / bucket name */
+    name;
+    /**
+     * Constructor for `OINOBlob`.
+     * @param params blob storage connection parameters
+     */
+    constructor(params) {
+        super();
+        this.blobParams = { ...params };
+        this.name = this.blobParams.container;
+    }
+    // ── OINODataSource passthrough stubs ──────────────────────────────────
+    // These are required by the abstract base class but are not meaningful
+    // for blob storage.  They return sensible no-op values so that
+    // OINODataField instances created by OINOBlobDataModel can function
+    // correctly for serialisation purposes.
+    printTableName(name) {
+        return name;
+    }
+    printColumnName(name) {
+        return name;
+    }
+    printCellAsValue(cellValue, _sqlType) {
+        if (cellValue === null || cellValue === undefined) {
+            return "";
+        }
+        if (cellValue instanceof Date) {
+            return cellValue.toISOString();
+        }
+        return String(cellValue);
+    }
+    printStringValue(s) {
+        return s;
+    }
+    parseValueAsCell(v, nativeType) {
+        if (nativeType === "DATETIME" && typeof v === "string" && v !== "") {
+            return new Date(v);
+        }
+        return v;
+    }
+    // ── Blob-specific filter helper ───────────────────────────────────────
+    /**
+     * Test whether a blob 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 blob entry to test
+     * @param filter filter predicate to evaluate
+     */
+    static matchesEntry(entry, filter) {
+        if (filter.isEmpty())
+            return true;
+        const op = filter.operator;
+        if (op === common_1.OINOQueryBooleanOperation.and) {
+            return OINOBlob.matchesEntry(entry, filter.leftSide) &&
+                OINOBlob.matchesEntry(entry, filter.rightSide);
+        }
+        if (op === common_1.OINOQueryBooleanOperation.or) {
+            return OINOBlob.matchesEntry(entry, filter.leftSide) ||
+                OINOBlob.matchesEntry(entry, filter.rightSide);
+        }
+        if (op === common_1.OINOQueryBooleanOperation.not) {
+            return !OINOBlob.matchesEntry(entry, filter.rightSide);
+        }
+        const fieldName = filter.leftSide;
+        const compareValue = filter.rightSide;
+        let fieldValue;
+        switch (fieldName) {
+            case "name":
+                fieldValue = entry.name;
+                break;
+            case "etag":
+                fieldValue = entry.etag;
+                break;
+            case "lastModified":
+                fieldValue = entry.lastModified;
+                break;
+            case "contentLength":
+                fieldValue = entry.contentLength;
+                break;
+            case "contentType":
+                fieldValue = entry.contentType;
+                break;
+            default: return true;
+        }
+        if (op === common_1.OINOQueryNullCheck.isnull)
+            return fieldValue === null;
+        if (op === common_1.OINOQueryNullCheck.isNotNull)
+            return fieldValue !== null;
+        if (fieldValue === null)
+            return false;
+        if (fieldValue instanceof Date) {
+            const ms = fieldValue.getTime();
+            const cmpMs = new Date(compareValue).getTime();
+            switch (op) {
+                case common_1.OINOQueryComparison.lt: return ms < cmpMs;
+                case common_1.OINOQueryComparison.le: return ms <= cmpMs;
+                case common_1.OINOQueryComparison.eq: return ms === cmpMs;
+                case common_1.OINOQueryComparison.ne: return ms !== cmpMs;
+                case common_1.OINOQueryComparison.ge: return ms >= cmpMs;
+                case common_1.OINOQueryComparison.gt: return ms > cmpMs;
+                default: return true;
+            }
+        }
+        if (typeof fieldValue === "number") {
+            const cmpNum = Number(compareValue);
+            switch (op) {
+                case common_1.OINOQueryComparison.lt: return fieldValue < cmpNum;
+                case common_1.OINOQueryComparison.le: return fieldValue <= cmpNum;
+                case common_1.OINOQueryComparison.eq: return fieldValue === cmpNum;
+                case common_1.OINOQueryComparison.ne: return fieldValue !== cmpNum;
+                case common_1.OINOQueryComparison.ge: return fieldValue >= cmpNum;
+                case common_1.OINOQueryComparison.gt: return fieldValue > cmpNum;
+                default: return true;
+            }
+        }
+        const strValue = String(fieldValue);
+        switch (op) {
+            case common_1.OINOQueryComparison.lt: return strValue < compareValue;
+            case common_1.OINOQueryComparison.le: return strValue <= compareValue;
+            case common_1.OINOQueryComparison.eq: return strValue === compareValue;
+            case common_1.OINOQueryComparison.ne: return strValue !== compareValue;
+            case common_1.OINOQueryComparison.ge: return strValue >= compareValue;
+            case common_1.OINOQueryComparison.gt: return strValue > compareValue;
+            case common_1.OINOQueryComparison.like: {
+                const escaped = compareValue
+                    .replace(BLOB_LIKE_ESCAPE_REGEX, "\\$&")
+                    .replace(BLOB_LIKE_PERCENT_REGEX, ".*")
+                    .replace(BLOB_LIKE_UNDERSCORE_REGEX, ".");
+                return new RegExp("^" + escaped + "$", "i").test(strValue);
+            }
+            default: return true;
+        }
+    }
+    /**
+     * Extract a blob/object name prefix from the filter that can be forwarded
+     * to the storage backend as a server-side query optimisation.
+     *
+     * Only two cases translate to a prefix:
+     * - `(name)-eq(value)`        → exact name match (use as prefix)
+     * - `(name)-like(prefix%)`    → trailing-wildcard prefix match
+     *
+     * AND-combined filters are explored recursively so that a name constraint
+     * nested inside a larger AND predicate is still extracted.
+     *
+     * @param filter filter to inspect
+     */
+    static extractNamePrefix(filter) {
+        if (filter.isEmpty())
+            return undefined;
+        const op = filter.operator;
+        if (typeof filter.leftSide === "string" && filter.leftSide === "name") {
+            if (op === common_1.OINOQueryComparison.eq) {
+                return filter.rightSide;
+            }
+            if (op === common_1.OINOQueryComparison.like) {
+                const pattern = filter.rightSide;
+                const body = pattern.slice(0, -1);
+                if (pattern.endsWith("%") && !body.includes("%") && !body.includes("_")) {
+                    return body;
+                }
+            }
+        }
+        if (op === common_1.OINOQueryBooleanOperation.and) {
+            return OINOBlob.extractNamePrefix(filter.leftSide) ??
+                OINOBlob.extractNamePrefix(filter.rightSide);
+        }
+        return undefined;
+    }
+}
+exports.OINOBlob = OINOBlob;

package/dist/cjs/OINOBlobApi.js

@@ -0,0 +1,180 @@
+"use strict";
+/*
+ * 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/.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OINOBlobApi = exports.OINOBlobApiResult = void 0;
+const common_1 = require("@oino-ts/common");
+class OINOBlobApiResult extends common_1.OINOApiResult {
+    /** Binary content of the blob (for GET with id) */
+    blobData;
+    /** Content-Type of the blob (for GET with id) */
+    blobDataType;
+    constructor(request, data, blobData, blobDataType) {
+        super(request, data);
+        this.blobData = blobData;
+        this.blobDataType = blobDataType;
+    }
+    async writeApiResponse(headers = {}) {
+        if (this.blobData) {
+            const response_headers = new Headers(headers);
+            response_headers.set("Content-Length", this.blobData.length.toString());
+            if (this.blobDataType) {
+                response_headers.set("Content-Type", this.blobDataType);
+            }
+            if (this.request.responseDownload) {
+                response_headers.set("Content-Disposition", `attachment; filename="${this.request.responseDownload}"`);
+            }
+            else {
+                response_headers.set("Content-Disposition", "inline");
+            }
+            return new Response(this.blobData, {
+                status: this.status,
+                statusText: this.statusText,
+                headers: response_headers
+            });
+        }
+        else {
+            return super.writeApiResponse(headers);
+        }
+    }
+}
+exports.OINOBlobApiResult = OINOBlobApiResult;
+/**
+ * REST API for blob storage.
+ *
+ * Supports two GET variants:
+ * - **GET without id** – lists all blobs under the configured prefix and
+ *   returns the metadata as JSON (or CSV) using `OINOModelSet`.
+ * - **GET with id** – downloads the named blob as a binary HTTP response
+ *   with the blob's own `Content-Type`.
+ *
+ * All other HTTP methods return `405 Method Not Allowed`.
+ */
+class OINOBlobApi extends common_1.OINOApi {
+    /** Blob storage backend */
+    blob;
+    /** Blob-specific data model (populated by `initializeDatamodel`) */
+    blobDatamodel = null;
+    /**
+     * Constructor.
+     *
+     * NOTE: `initializeDatamodel` (or `OINOBlobFactory.createApi`) must be
+     * called before the first request is dispatched.
+     *
+     * @param blob blob storage backend
+     * @param params API parameters (`tableName` is used as the blob prefix)
+     */
+    constructor(blob, params) {
+        super(blob, params);
+        this.blob = blob;
+    }
+    /**
+     * Attach the static blob data model and mark the API as initialised.
+     *
+     * @param datamodel `OINOBlobDataModel` instance for this API
+     */
+    initializeDatamodel(datamodel) {
+        this.blobDatamodel = datamodel;
+        this.datamodel = datamodel;
+        this.initialized = true;
+    }
+    // ── OINOApi abstract implementations ─────────────────────────────────
+    async doApiRequest(request) {
+        if (!this.initialized) {
+            throw new Error(common_1.OINO_ERROR_PREFIX + ": OINOBlobApi is not initialized yet!");
+        }
+        common_1.OINOLog.debug("@oino-ts/blob", "OINOBlobApi", "doApiRequest", "Request", { method: request.method, id: request.rowId });
+        const result = new OINOBlobApiResult(request);
+        if (request.method === "GET") {
+            if (!request.rowId) {
+                // ── List blobs ───────────────────────────────────────────────
+                try {
+                    const entries = await this.blob.listEntries(request.queryParams?.filter);
+                    const dataset = this.blobDatamodel.entriesToDataset(entries);
+                    result.data = new common_1.OINOModelSet(this.datamodel, dataset, request.queryParams);
+                }
+                catch (e) {
+                    result.setError(500, "Error listing blobs: " + e.message, "DoGet");
+                    common_1.OINOLog.exception("@oino-ts/blob", "OINOBlobApi", "doApiRequest", "exception in list request", { message: e.message, stack: e.stack });
+                }
+            }
+            else {
+                // ── Download blob ────────────────────────────────────────────
+                try {
+                    const name = decodeURIComponent(request.rowId);
+                    const fetch_result = await this.blob.fetchEntry(name);
+                    result.blobData = fetch_result.content;
+                    result.blobDataType = fetch_result.contentType;
+                }
+                catch (e) {
+                    result.setError(500, "Error fetching blob: " + e.message, "DoGet");
+                    common_1.OINOLog.exception("@oino-ts/blob", "OINOBlobApi", "doApiRequest", "exception in fetch request", { message: e.message, stack: e.stack });
+                }
+            }
+        }
+        else if (request.method === "POST" || request.method === "PUT") {
+            if (!request.rowId) {
+                result.setError(400, "HTTP " + request.method + " method requires an URL ID (blob name)!", "DoRequest");
+            }
+            else {
+                try {
+                    const name = decodeURIComponent(request.rowId);
+                    const content_type = request.headers.get("content-type") ?? "application/octet-stream";
+                    const data = request.rowData;
+                    const content = data instanceof Uint8Array ? data : request.bodyAsBuffer();
+                    await this.blob.uploadEntry(name, content, content_type);
+                }
+                catch (e) {
+                    result.setError(500, "Error uploading blob: " + e.message, "DoPost");
+                    common_1.OINOLog.exception("@oino-ts/blob", "OINOBlobApi", "doApiRequest", "exception in upload request", { message: e.message, stack: e.stack });
+                }
+            }
+        }
+        else if (request.method === "DELETE") {
+            if (!request.rowId) {
+                result.setError(400, "HTTP DELETE method requires an URL ID (blob name)!", "DoRequest");
+            }
+            else {
+                try {
+                    const name = decodeURIComponent(request.rowId);
+                    await this.blob.deleteEntry(name);
+                }
+                catch (e) {
+                    result.setError(500, "Error deleting blob: " + e.message, "DoDelete");
+                    common_1.OINOLog.exception("@oino-ts/blob", "OINOBlobApi", "doApiRequest", "exception in delete request", { message: e.message, stack: e.stack });
+                }
+            }
+        }
+        else {
+            result.setError(405, "Unsupported HTTP method '" + request.method + "' for OINOBlobApi", "DoRequest");
+        }
+        return result;
+    }
+    async doHttpRequest(request, rowId, rowData, queryParams) {
+        const api_request = common_1.OINOApiRequest.fromHttpRequest(request, rowId, rowData, queryParams);
+        return this.doApiRequest(api_request);
+    }
+    async doRequest(method, rowId, rowData, queryParams, contentType = common_1.OINOContentType.json) {
+        return this.doApiRequest(new common_1.OINOApiRequest({
+            method,
+            rowId,
+            rowData,
+            queryParams,
+            requestType: contentType
+        }));
+    }
+    async doBatchUpdate(method, _rowId, _rowData, _queryParams) {
+        const result = new common_1.OINOApiResult(new common_1.OINOApiRequest({ method }));
+        result.setError(405, "OINOBlobApi does not support batch updates", "DoBatchUpdate");
+        return result;
+    }
+    async doBatchApiRequest(request) {
+        const result = new common_1.OINOApiResult(request);
+        result.setError(405, "OINOBlobApi does not support batch updates", "DoBatchApiRequest");
+        return result;
+    }
+}
+exports.OINOBlobApi = OINOBlobApi;

package/dist/cjs/OINOBlobConstants.js

@@ -0,0 +1,7 @@
+"use strict";
+/*
+ * 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/.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/OINOBlobDataModel.js

@@ -0,0 +1,69 @@
+"use strict";
+/*
+ * 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/.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OINOBlobDataModel = void 0;
+const common_1 = require("@oino-ts/common");
+/**
+ * Static data model for blob listings.
+ *
+ * Fields are added by the blob implementation's `initializeApiDatamodel`
+ * method, so the exact set depends on what the storage backend supports.
+ * The canonical order is:
+ *   1. `name`          – full blob name (primary key, string)
+ *   2. `etag`          – entity tag (string)
+ *   3. `lastModified`  – last modification timestamp (datetime)
+ *   4. `contentLength` – size in bytes (number)
+ *   5. `contentType`   – MIME type (string) – omitted when not supported
+ */
+class OINOBlobDataModel extends common_1.OINODataModel {
+    /** Reference to the owning blob API */
+    blobApi;
+    /**
+     * Constructor.  Fields are added externally by the blob implementation
+     * via `initializeApiDatamodel`.
+     *
+     * @param api the `OINOBlobApi` that owns this data model
+     */
+    constructor(api) {
+        super(api);
+        this.blobApi = api;
+    }
+    /**
+     * Convert an array of blob entries into an in-memory dataset whose
+     * columns match the fields present in this model.
+     *
+     * @param entries blob entries from the storage backend
+     */
+    entriesToDataset(entries) {
+        const fieldNames = this.fields.map(f => f.name);
+        const rows = entries.map(e => {
+            const row = [];
+            for (const name of fieldNames) {
+                switch (name) {
+                    case "name":
+                        row.push(e.name);
+                        break;
+                    case "etag":
+                        row.push(e.etag);
+                        break;
+                    case "lastModified":
+                        row.push(e.lastModified);
+                        break;
+                    case "contentLength":
+                        row.push(e.contentLength);
+                        break;
+                    case "contentType":
+                        row.push(e.contentType);
+                        break;
+                }
+            }
+            return row;
+        });
+        return new common_1.OINOMemoryDataset(rows);
+    }
+}
+exports.OINOBlobDataModel = OINOBlobDataModel;

package/dist/cjs/OINOBlobFactory.js

@@ -0,0 +1,71 @@
+"use strict";
+/*
+ * 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/.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OINOBlobFactory = void 0;
+const OINOBlobApi_js_1 = require("./OINOBlobApi.js");
+/**
+ * Static factory for creating `OINOBlob` instances and `OINOBlobApi` instances
+ * from registered provider classes.
+ *
+ * Usage:
+ * ```ts
+ * OINOBlobFactory.registerBlob("OINOBlobAzureTable", OINOBlobAzureTable)
+ * const blob = await OINOBlobFactory.createBlob({ type: "OINOBlobAzureTable", ... })
+ * const api  = await OINOBlobFactory.createApi(blob, { apiName: "files", tableName: "uploads/" })
+ * ```
+ */
+class OINOBlobFactory {
+    static _registry = {};
+    /**
+     * Register a blob provider class under the given name.
+     *
+     * @param name name used in `OINOBlobParams.type`
+     * @param blobClass constructor of the provider
+     */
+    static registerBlob(name, blobClass) {
+        this._registry[name] = blobClass;
+    }
+    /**
+     * Create and optionally connect/validate a blob 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 async createBlob(params, connect = true, validate = true) {
+        const BlobClass = this._registry[params.type];
+        if (!BlobClass) {
+            throw new Error("Unsupported blob type: " + params.type);
+        }
+        const blob = new BlobClass(params);
+        if (connect) {
+            const connect_res = await blob.connect();
+            if (!connect_res.success) {
+                throw new Error("Blob connection failed: " + connect_res.statusText);
+            }
+        }
+        if (validate) {
+            const validate_res = await blob.validate();
+            if (!validate_res.success) {
+                throw new Error("Blob validation failed: " + validate_res.statusText);
+            }
+        }
+        return blob;
+    }
+    /**
+     * Create an `OINOBlobApi` and initialise its data model.
+     *
+     * @param blob blob backend to use
+     * @param params API parameters (`tableName` is used as the blob prefix)
+     */
+    static async createApi(blob, params) {
+        const api = new OINOBlobApi_js_1.OINOBlobApi(blob, params);
+        await blob.initializeApiDatamodel(api);
+        return api;
+    }
+}
+exports.OINOBlobFactory = OINOBlobFactory;

package/dist/cjs/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OINOBlobApiResult = exports.OINOBlobApi = exports.OINOBlobFactory = exports.OINOBlobDataModel = exports.OINOBlob = void 0;
+var OINOBlob_js_1 = require("./OINOBlob.js");
+Object.defineProperty(exports, "OINOBlob", { enumerable: true, get: function () { return OINOBlob_js_1.OINOBlob; } });
+var OINOBlobDataModel_js_1 = require("./OINOBlobDataModel.js");
+Object.defineProperty(exports, "OINOBlobDataModel", { enumerable: true, get: function () { return OINOBlobDataModel_js_1.OINOBlobDataModel; } });
+var OINOBlobFactory_js_1 = require("./OINOBlobFactory.js");
+Object.defineProperty(exports, "OINOBlobFactory", { enumerable: true, get: function () { return OINOBlobFactory_js_1.OINOBlobFactory; } });
+var OINOBlobApi_js_1 = require("./OINOBlobApi.js");
+Object.defineProperty(exports, "OINOBlobApi", { enumerable: true, get: function () { return OINOBlobApi_js_1.OINOBlobApi; } });
+Object.defineProperty(exports, "OINOBlobApiResult", { enumerable: true, get: function () { return OINOBlobApi_js_1.OINOBlobApiResult; } });