## Features
- **Blob Storage**: Upload, download, list, and manage blobs with SAS URL support
- **Table Storage**: Complete CRUD operations for Azure Table Storage
- **Queue Storage**: Send, receive, and manage queue messages
- **Managed Identity Support**: Passwordless authentication using Azure Managed Identity (system-assigned and user-assigned)
- **SAS URL Support**: Generate Shared Access Signature URLs — User Delegation SAS with Managed Identity, Service SAS with connection strings
- **TypeScript Support**: Full type definitions included
- **Error Handling**: Built-in error handling and validation
## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Blob Storage](#blob-storage)
- [Table Storage](#table-storage)
- [Queue Storage](#queue-storage)
- [Configuration](#configuration)
- [Error Handling](#error-handling)
- [Best Practices](#best-practices)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)
## Installation
```bash
npm install @akadenia/azure-storage --save
```
## Quick Start
### Prerequisites
You can authenticate using either:
- **Connection String**: Get this from the Azure Portal under your storage account's "Access keys" section
- **Managed Identity**: For applications running in Azure (recommended for production)
**Option 1: Connection string**
```typescript
import { BlobStorage, TableStorage, QueueStorage } from '@akadenia/azure-storage';
const connectionString = "DefaultEndpointsProtocol=https;AccountName=yourstorageaccount;AccountKey=yourkey;EndpointSuffix=core.windows.net";
const blobStorage = new BlobStorage(connectionString);
const tableStorage = new TableStorage(connectionString, 'tableName');
const queueStorage = new QueueStorage(connectionString);
```
**Option 2: Managed Identity (recommended for production)**
```typescript
import { BlobStorage, TableStorage, QueueStorage } from '@akadenia/azure-storage';
const blobStorage = new BlobStorage({ accountName: 'yourstorageaccount' });
const tableStorage = new TableStorage({ accountName: 'yourstorageaccount', tableName: 'tableName' });
const queueStorage = new QueueStorage({ accountName: 'yourstorageaccount' });
```
---
## Blob Storage
The `BlobStorage` class provides methods to interact with Azure Blob Storage.
### Basic Setup
```typescript
import { BlobStorage } from '@akadenia/azure-storage';
const blobStorage = new BlobStorage(connectionString);
```
### Container Operations
```typescript
// Create a container
const containerCreated = await blobStorage.createContainer('my-container');
console.log('Container created:', containerCreated);
// Delete a container
const containerDeleted = await blobStorage.deleteContainer('my-container');
console.log('Container deleted:', containerDeleted);
```
### Upload Operations
```typescript
// Upload data from Buffer
const data = Buffer.from('Hello, Azure Blob Storage!');
const uploaded = await blobStorage.uploadData('my-container', 'my-blob.txt', data, {
blobContentType: 'text/plain'
});
// Upload from stream
import { Readable } from 'stream';
const stream = Readable.from(['Stream data content']);
await blobStorage.uploadStream('my-container', 'stream-blob.txt', stream, {
blobContentType: 'text/plain'
});
// Upload with additional headers
await blobStorage.uploadData('my-container', 'document.pdf', pdfBuffer, {
blobContentType: 'application/pdf',
blobCacheControl: 'max-age=3600',
blobContentEncoding: 'gzip'
});
// Legacy upload method
await blobStorage.upload('my-container', 'file.pdf', buffer, buffer.length, 'application/pdf');
```
### Download Operations
```typescript
// Download blob as Buffer
const blobData = await blobStorage.downloadBlob('my-container', 'my-blob.txt');
console.log('Downloaded content:', blobData.toString());
// Check if blob exists before downloading
const exists = await blobStorage.blobExists('my-container', 'my-blob.txt');
if (exists) {
const data = await blobStorage.downloadBlob('my-container', 'my-blob.txt');
}
```
### List Operations
```typescript
// List all blobs with a prefix
const blobs = await blobStorage.listBlobs('my-container', 'documents/');
blobs.forEach(blob => {
console.log(`Blob: ${blob.name}, Size: ${blob.properties.contentLength}`);
});
```
### Delete Operations
```typescript
const deleted = await blobStorage.deleteBlob('my-container', 'my-blob.txt');
console.log('Blob deleted:', deleted);
```
### SAS URL Generation
`generateSASUrl` supports two SAS token types automatically:
- **User Delegation SAS** — used with Managed Identity (more secure, no account keys)
- **Service SAS** — used with connection string authentication
```typescript
import { BlobPermissions } from '@akadenia/azure-storage';
// Read-only SAS, 1 hour expiry
const sasUrl = await blobStorage.generateSASUrl('my-container', 'my-blob.txt', {
startsOn: new Date(),
expiresOn: new Date(Date.now() + 3600 * 1000),
permissions: [BlobPermissions.READ]
});
console.log('SAS URL:', sasUrl.fullUrlWithSAS);
// Write-enabled container-level SAS
const containerSas = await blobStorage.generateSASUrl('my-container', undefined, {
permissions: [BlobPermissions.ADD, BlobPermissions.WRITE],
expiresOn: new Date(Date.now() + 24 * 3600 * 1000)
});
```
#### SAS Permissions
```typescript
import { BlobPermissions } from '@akadenia/azure-storage';
BlobPermissions.READ // "r"
BlobPermissions.WRITE // "w"
BlobPermissions.CREATE // "c"
BlobPermissions.DELETE // "d"
BlobPermissions.ADD // "a"
```
---
## Table Storage
The `TableStorage` class provides methods to interact with Azure Table Storage.
### Basic Setup
```typescript
import { TableStorage, ITableEntity } from '@akadenia/azure-storage';
const tableStorage = new TableStorage(connectionString, 'MyTable');
```
### Table Management
```typescript
const tableCreated = await tableStorage.createTable();
const tableDeleted = await tableStorage.deleteTable();
```
### Entity Operations
```typescript
interface UserEntity extends ITableEntity {
partitionKey: string;
rowKey: string;
name: string;
email: string;
age: number;
isActive: boolean;
}
// Insert
const user: UserEntity = {
partitionKey: 'users',
rowKey: 'user-123',
name: 'John Doe',
email: 'john@example.com',
age: 30,
isActive: true
};
await tableStorage.insert(user);
// Get
const retrievedUser = await tableStorage.get('users', 'user-123');
// Update
user.age = 31;
await tableStorage.update(user);
// Upsert (insert or update)
await tableStorage.upsert(newUser);
// Delete
await tableStorage.delete('users', 'user-123');
```
### List Operations
```typescript
// List all entities
const allUsers = await tableStorage.list
A TypeScript library that wraps Azure Blob, Table, and Queue Storage with a clean, consistent API. Supports both connection strings and Managed Identity — so it works the same in local dev and production Azure environments.
[Documentation](https://akadenia.com/packages/akadenia-azure-storage) · [GitHub](https://github.com/akadenia/AkadeniaAzureStorage) · [Issues](https://github.com/akadenia/AkadeniaAzureStorage/issues)