@basaltkit/storage-azure 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machize Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,41 @@
+# @basaltkit/storage-azure
+
+An **Azure Blob Storage** driver for [`@basaltkit/storage`](https://www.npmjs.com/package/@basaltkit/storage): stores files in Azure Blob without changing your app code. You need this module when you run on Azure and want Blob Storage instead of S3, GCS, or local disk.
+
+## Installation
+
+```bash
+pnpm add @basaltkit/storage-azure @azure/storage-blob
+```
+
+`@azure/storage-blob` is a **peer dependency**.
+
+## Usage
+
+```ts
+import { storagePlugin } from '@basaltkit/storage'
+import { AzureBlobStorageDriver } from '@basaltkit/storage-azure'
+
+storagePlugin({
+  disks: {
+    uploads: {
+      driver: new AzureBlobStorageDriver({ container: 'uploads', connectionString: process.env.AZURE_STORAGE_CONNECTION_STRING }),
+    },
+  },
+})
+```
+
+Implements the `StorageDriver` contract — `put`, `get`, `exists`, `delete`, `list`, and **signed URLs** (SAS via `temporaryUrl`). Per-tenant isolation is automatic via `Disk`.
+
+## Testable without the cloud
+
+The container is **injectable**, so the driver logic can be tested with a fake — no Azure needed:
+
+```ts
+new AzureBlobStorageDriver({ container: 'c', client: fakeContainer })
+```
+
+## How it connects to other modules
+
+- **`@basaltkit/storage`** — this is a driver for that package; the API (`Disk`, `storagePlugin`) comes from there.
+- Sibling drivers: `S3StorageDriver` (in core) and [`@basaltkit/storage-gcs`](https://www.npmjs.com/package/@basaltkit/storage-gcs).

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { StorageDriver, PutOptions } from '@basaltkit/storage';
+
+/** The subset of an `@azure/storage-blob` BlockBlobClient this driver uses. */
+interface AzureBlobLike {
+    uploadData(data: Buffer, options?: {
+        blobHTTPHeaders?: {
+            blobContentType?: string;
+        };
+    }): Promise<unknown>;
+    downloadToBuffer(): Promise<Buffer>;
+    exists(): Promise<boolean>;
+    deleteIfExists(): Promise<{
+        succeeded: boolean;
+    }>;
+    generateSasUrl(options: {
+        permissions: string;
+        expiresOn: Date;
+    }): Promise<string>;
+}
+/** The subset of an `@azure/storage-blob` ContainerClient this driver uses. */
+interface AzureContainerLike {
+    getBlockBlobClient(path: string): AzureBlobLike;
+    listBlobsFlat(options?: {
+        prefix?: string;
+    }): AsyncIterable<{
+        name: string;
+    }>;
+}
+interface AzureDriverOptions {
+    container: string;
+    connectionString?: string;
+    /** Injectable container — defaults to `@azure/storage-blob`. Tests pass a fake. */
+    client?: AzureContainerLike;
+}
+/**
+ * Azure Blob Storage driver for `@basaltkit/storage`. Uses `@azure/storage-blob`
+ * (an optional peer dependency) via an injectable container client, so its
+ * logic is unit-tested without touching Azure.
+ */
+declare class AzureBlobStorageDriver implements StorageDriver {
+    private readonly options;
+    readonly name = "azure";
+    private containerPromise;
+    constructor(options: AzureDriverOptions);
+    put(path: string, content: Buffer | string, options?: PutOptions): Promise<void>;
+    get(path: string): Promise<Buffer>;
+    exists(path: string): Promise<boolean>;
+    delete(path: string): Promise<boolean>;
+    list(prefix: string): Promise<string[]>;
+    temporaryUrl(path: string, expiresInMs: number): Promise<string>;
+    disconnect(): Promise<void>;
+    private container;
+}
+
+export { type AzureBlobLike, AzureBlobStorageDriver, type AzureContainerLike, type AzureDriverOptions };

package/dist/index.js

@@ -0,0 +1,54 @@
+// src/index.ts
+import { StorageFileNotFoundError } from "@basaltkit/storage";
+var isNotFound = (error) => error?.statusCode === 404 || error?.code === "BlobNotFound";
+var AzureBlobStorageDriver = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  name = "azure";
+  containerPromise;
+  async put(path, content, options) {
+    const data = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    await (await this.container()).getBlockBlobClient(path).uploadData(data, options?.contentType !== void 0 ? { blobHTTPHeaders: { blobContentType: options.contentType } } : {});
+  }
+  async get(path) {
+    try {
+      return await (await this.container()).getBlockBlobClient(path).downloadToBuffer();
+    } catch (error) {
+      if (isNotFound(error)) throw new StorageFileNotFoundError(path);
+      throw error;
+    }
+  }
+  async exists(path) {
+    return (await this.container()).getBlockBlobClient(path).exists();
+  }
+  async delete(path) {
+    const result = await (await this.container()).getBlockBlobClient(path).deleteIfExists();
+    return result.succeeded;
+  }
+  async list(prefix) {
+    const names = [];
+    for await (const blob of (await this.container()).listBlobsFlat({ prefix })) names.push(blob.name);
+    return names;
+  }
+  async temporaryUrl(path, expiresInMs) {
+    return (await this.container()).getBlockBlobClient(path).generateSasUrl({ permissions: "r", expiresOn: new Date(Date.now() + expiresInMs) });
+  }
+  async disconnect() {
+  }
+  container() {
+    if (!this.containerPromise) {
+      this.containerPromise = this.options.client ? Promise.resolve(this.options.client) : (async () => {
+        if (!this.options.connectionString) throw new Error("connectionString is required for the Azure driver.");
+        const specifier = "@azure/storage-blob";
+        const mod = await import(specifier);
+        return mod.BlobServiceClient.fromConnectionString(this.options.connectionString).getContainerClient(this.options.container);
+      })();
+    }
+    return this.containerPromise;
+  }
+};
+export {
+  AzureBlobStorageDriver
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@basaltkit/storage-azure",
+  "version": "1.0.0",
+  "description": "Azure Blob Storage driver for @basaltkit/storage — put/get/list/delete/SAS URLs over @azure/storage-blob, with an injectable client for testing.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@basaltkit/storage": "^1.0.0"
+  },
+  "peerDependencies": {
+    "@azure/storage-blob": "^12.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "@basaltkit/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/storage-azure"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/storage-azure#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "storage",
+    "azure",
+    "blob"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}