@oino-ts/blob 1.0.0

package/dist/types/OINOBlobDataModel.d.ts

@@ -0,0 +1,33 @@
+import { OINODataModel, OINOMemoryDataset } from "@oino-ts/common";
+import { OINOBlobApi } from "./OINOBlobApi.js";
+import { OINOBlobEntry } from "./OINOBlobConstants.js";
+/**
+ * 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
+ */
+export declare class OINOBlobDataModel extends OINODataModel {
+    /** Reference to the owning blob API */
+    readonly blobApi: OINOBlobApi;
+    /**
+     * Constructor.  Fields are added externally by the blob implementation
+     * via `initializeApiDatamodel`.
+     *
+     * @param api the `OINOBlobApi` that owns this data model
+     */
+    constructor(api: OINOBlobApi);
+    /**
+     * 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: OINOBlobEntry[]): OINOMemoryDataset;
+}

package/dist/types/OINOBlobFactory.d.ts

@@ -0,0 +1,40 @@
+import { OINOApiParams } from "@oino-ts/common";
+import { OINOBlobParams, OINOBlobConstructor } from "./OINOBlobConstants.js";
+import { OINOBlob } from "./OINOBlob.js";
+import { OINOBlobApi } from "./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/" })
+ * ```
+ */
+export declare class OINOBlobFactory {
+    private 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: string, blobClass: OINOBlobConstructor): void;
+    /**
+     * 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 createBlob(params: OINOBlobParams, connect?: boolean, validate?: boolean): Promise<OINOBlob>;
+    /**
+     * 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 createApi(blob: OINOBlob, params: OINOApiParams): Promise<OINOBlobApi>;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,5 @@
+export { OINOBlob } from "./OINOBlob.js";
+export { OINOBlobDataModel } from "./OINOBlobDataModel.js";
+export { OINOBlobFactory } from "./OINOBlobFactory.js";
+export { OINOBlobApi, OINOBlobApiResult } from "./OINOBlobApi.js";
+export { type OINOBlobConstructor, type OINOBlobParams, type OINOBlobEntry, type OINOBlobFetchResult } from "./OINOBlobConstants.js";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@oino-ts/blob",
+  "version": "1.0.0",
+  "description": "OINO TS library package for publishing blob 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": [
+    "blob",
+    "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/OINOBlob.ts

@@ -0,0 +1,238 @@
+/*
+ * 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, OINOResult, OINOApi, OINOQueryFilter, OINOQueryBooleanOperation, OINOQueryComparison, OINOQueryNullCheck } from "@oino-ts/common"
+import { OINOBlobParams, OINOBlobEntry, OINOBlobFetchResult } from "./OINOBlobConstants.js"
+
+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`.
+ */
+export abstract class OINOBlob extends OINODataSource {
+
+    protected readonly blobParams: OINOBlobParams
+
+    /** Container / bucket name */
+    readonly name: string
+
+    /**
+     * Constructor for `OINOBlob`.
+     * @param params blob storage connection parameters
+     */
+    constructor(params: OINOBlobParams) {
+        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: string): string {
+        return name
+    }
+
+    printColumnName(name: string): string {
+        return name
+    }
+
+    printCellAsValue(cellValue: OINODataCell, _sqlType: 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
+    }
+
+    // ── 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
+     */
+    protected static matchesEntry(entry: OINOBlobEntry, filter: OINOQueryFilter): boolean {
+        if (filter.isEmpty()) return true
+
+        const op = filter.operator
+
+        if (op === OINOQueryBooleanOperation.and) {
+            return OINOBlob.matchesEntry(entry, filter.leftSide as OINOQueryFilter) &&
+                   OINOBlob.matchesEntry(entry, filter.rightSide as OINOQueryFilter)
+        }
+        if (op === OINOQueryBooleanOperation.or) {
+            return OINOBlob.matchesEntry(entry, filter.leftSide as OINOQueryFilter) ||
+                   OINOBlob.matchesEntry(entry, filter.rightSide as OINOQueryFilter)
+        }
+        if (op === OINOQueryBooleanOperation.not) {
+            return !OINOBlob.matchesEntry(entry, filter.rightSide as OINOQueryFilter)
+        }
+
+        const fieldName = filter.leftSide as string
+        const compareValue = filter.rightSide as string
+
+        let fieldValue: string | number | Date | null
+        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 === OINOQueryNullCheck.isnull) return fieldValue === null
+        if (op === 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 OINOQueryComparison.lt: return ms < cmpMs
+                case OINOQueryComparison.le: return ms <= cmpMs
+                case OINOQueryComparison.eq: return ms === cmpMs
+                case OINOQueryComparison.ne: return ms !== cmpMs
+                case OINOQueryComparison.ge: return ms >= cmpMs
+                case OINOQueryComparison.gt: return ms > cmpMs
+                default: return true
+            }
+        }
+
+        if (typeof fieldValue === "number") {
+            const cmpNum = Number(compareValue)
+            switch (op) {
+                case OINOQueryComparison.lt: return fieldValue < cmpNum
+                case OINOQueryComparison.le: return fieldValue <= cmpNum
+                case OINOQueryComparison.eq: return fieldValue === cmpNum
+                case OINOQueryComparison.ne: return fieldValue !== cmpNum
+                case OINOQueryComparison.ge: return fieldValue >= cmpNum
+                case OINOQueryComparison.gt: return fieldValue > cmpNum
+                default: return true
+            }
+        }
+
+        const strValue = String(fieldValue)
+        switch (op) {
+            case OINOQueryComparison.lt: return strValue < compareValue
+            case OINOQueryComparison.le: return strValue <= compareValue
+            case OINOQueryComparison.eq: return strValue === compareValue
+            case OINOQueryComparison.ne: return strValue !== compareValue
+            case OINOQueryComparison.ge: return strValue >= compareValue
+            case OINOQueryComparison.gt: return strValue > compareValue
+            case 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
+     */
+    protected static extractNamePrefix(filter: OINOQueryFilter): string | undefined {
+        if (filter.isEmpty()) return undefined
+
+        const op = filter.operator
+
+        if (typeof filter.leftSide === "string" && filter.leftSide === "name") {
+            if (op === OINOQueryComparison.eq) {
+                return filter.rightSide as string
+            }
+            if (op === OINOQueryComparison.like) {
+                const pattern = filter.rightSide as string
+                const body = pattern.slice(0, -1)
+                if (pattern.endsWith("%") && !body.includes("%") && !body.includes("_")) {
+                    return body
+                }
+            }
+        }
+
+        if (op === OINOQueryBooleanOperation.and) {
+            return OINOBlob.extractNamePrefix(filter.leftSide as OINOQueryFilter) ??
+                   OINOBlob.extractNamePrefix(filter.rightSide as OINOQueryFilter)
+        }
+
+        return undefined
+    }
+
+    // ── Blob-specific abstract interface ──────────────────────────────────
+
+    /**
+     * List blob entries, optionally filtered by a query filter.  Implementations
+     * should apply native query filtering where possible and fall back to
+     * in-memory result filtering for predicates that cannot be expressed as a
+     * native query.
+     *
+     * @param filter optional query filter to apply to the results
+     */
+    abstract listEntries(filter?: OINOQueryFilter): Promise<OINOBlobEntry[]>
+
+    /**
+     * Fetch the binary content and content-type of a named blob.
+     *
+     * @param name full blob name (path within the container)
+     */
+    abstract fetchEntry(name: string): Promise<OINOBlobFetchResult>
+
+    /**
+     * Upload (create or replace) a blob with the given binary content.
+     *
+     * @param name full blob name (path within the container)
+     * @param content binary content to store
+     * @param contentType MIME type of the content (e.g. `"image/jpeg"`)
+     */
+    abstract uploadEntry(name: string, content: Uint8Array, contentType: string): Promise<void>
+
+    /**
+     * Delete a named blob.
+     *
+     * @param name full blob name (path within the container)
+     */
+    abstract deleteEntry(name: string): Promise<void>
+}