@oino-ts/blob 1.0.0

package/src/OINOBlobDataModel.ts

@@ -0,0 +1,66 @@
+/*
+ * 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 {
+    OINODataModel,
+    OINOMemoryDataset,
+    OINODataRow,
+} 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 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) {
+        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: OINOBlobEntry[]): OINOMemoryDataset {
+        const fieldNames = this.fields.map(f => f.name)
+        const rows: OINODataRow[] = entries.map(e => {
+            const row: OINODataRow = []
+            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 OINOMemoryDataset(rows)
+    }
+}

package/src/OINOBlobFactory.ts

@@ -0,0 +1,80 @@
+/*
+ * 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 { OINOApiParams } from "@oino-ts/common"
+import { OINOBlobParams, OINOBlobConstructor } from "./OINOBlobConstants.js"
+import { OINOBlob } from "./OINOBlob.js"
+import { OINOBlobApi } from "./OINOBlobApi.js"
+import { OINOBlobDataModel } from "./OINOBlobDataModel.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 class OINOBlobFactory {
+    private static _registry: Record<string, OINOBlobConstructor> = {}
+
+    /**
+     * 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 {
+        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: OINOBlobParams,
+        connect: boolean = true,
+        validate: boolean = true
+    ): Promise<OINOBlob> {
+        const BlobClass = this._registry[params.type]
+        if (!BlobClass) {
+            throw new Error("Unsupported blob type: " + params.type)
+        }
+        const blob: OINOBlob = 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: OINOBlob, params: OINOApiParams): Promise<OINOBlobApi> {
+        const api = new OINOBlobApi(blob, params)
+        await blob.initializeApiDatamodel(api)
+        return api
+    }
+}

package/src/index.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"