Azure Storage Queue Ts

1---
2name: azure-storage-queue-ts
3description: |
4  Azure Queue Storage JavaScript/TypeScript SDK (@azure/storage-queue) for message queue operations. Use for sending, receiving, peeking, and deleting messages in queues. Supports visibility timeout, message encoding, and batch operations. Triggers: "queue storage", "@azure/storage-queue", "QueueServiceClient", "QueueClient", "send message", "receive message", "dequeue", "visibility timeout".
5package: "@azure/storage-queue"
6---
7 
8# @azure/storage-queue (TypeScript/JavaScript)
9 
10SDK for Azure Queue Storage operations — send, receive, peek, and manage messages in queues.
11 
12## Installation
13 
14```bash
15npm install @azure/storage-queue @azure/identity
16```
17 
18**Current Version**: 12.x  
19**Node.js**: >= 18.0.0
20 
21## Environment Variables
22 
23```bash
24AZURE_STORAGE_ACCOUNT_NAME=<account-name>
25AZURE_STORAGE_ACCOUNT_KEY=<account-key>
26# OR connection string
27AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
28```
29 
30## Authentication
31 
32### DefaultAzureCredential (Recommended)
33 
34```typescript
35import { QueueServiceClient } from "@azure/storage-queue";
36import { DefaultAzureCredential } from "@azure/identity";
37 
38const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
39const client = new QueueServiceClient(
40  `https://${accountName}.queue.core.windows.net`,
41  new DefaultAzureCredential()
42);
43```
44 
45### Connection String
46 
47```typescript
48import { QueueServiceClient } from "@azure/storage-queue";
49 
50const client = QueueServiceClient.fromConnectionString(
51  process.env.AZURE_STORAGE_CONNECTION_STRING!
52);
53```
54 
55### StorageSharedKeyCredential (Node.js only)
56 
57```typescript
58import { QueueServiceClient, StorageSharedKeyCredential } from "@azure/storage-queue";
59 
60const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
61const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY!;
62 
63const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
64const client = new QueueServiceClient(
65  `https://${accountName}.queue.core.windows.net`,
66  sharedKeyCredential
67);
68```
69 
70### SAS Token
71 
72```typescript
73import { QueueServiceClient } from "@azure/storage-queue";
74 
75const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
76const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN!;
77 
78const client = new QueueServiceClient(
79  `https://${accountName}.queue.core.windows.net${sasToken}`
80);
81```
82 
83## Client Hierarchy
84 
85```
86QueueServiceClient (account level)
87└── QueueClient (queue level)
88    └── Messages (send, receive, peek, delete)
89```
90 
91## Queue Operations
92 
93### Create Queue
94 
95```typescript
96const queueClient = client.getQueueClient("my-queue");
97await queueClient.create();
98 
99// Or create if not exists
100await queueClient.createIfNotExists();
101```
102 
103### List Queues
104 
105```typescript
106for await (const queue of client.listQueues()) {
107  console.log(queue.name);
108}
109 
110// With prefix filter
111for await (const queue of client.listQueues({ prefix: "task-" })) {
112  console.log(queue.name);
113}
114```
115 
116### Delete Queue
117 
118```typescript
119await queueClient.delete();
120 
121// Or delete if exists
122await queueClient.deleteIfExists();
123```
124 
125### Get Queue Properties
126 
127```typescript
128const properties = await queueClient.getProperties();
129console.log("Approximate message count:", properties.approximateMessagesCount);
130console.log("Metadata:", properties.metadata);
131```
132 
133### Set Queue Metadata
134 
135```typescript
136await queueClient.setMetadata({
137  department: "engineering",
138  priority: "high",
139});
140```
141 
142## Message Operations
143 
144### Send Message
145 
146```typescript
147const queueClient = client.getQueueClient("my-queue");
148 
149// Simple message
150await queueClient.sendMessage("Hello, World!");
151 
152// With options
153await queueClient.sendMessage("Delayed message", {
154  visibilityTimeout: 60, // Hidden for 60 seconds
155  messageTimeToLive: 3600, // Expires in 1 hour
156});
157 
158// JSON message (must be string)
159const task = { type: "process", data: { id: 123 } };
160await queueClient.sendMessage(JSON.stringify(task));
161```
162 
163### Receive Messages
164 
165```typescript
166// Receive up to 32 messages (default: 1)
167const response = await queueClient.receiveMessages({
168  numberOfMessages: 10,
169  visibilityTimeout: 30, // 30 seconds to process
170});
171 
172for (const message of response.receivedMessageItems) {
173  console.log("Message ID:", message.messageId);
174  console.log("Content:", message.messageText);
175  console.log("Dequeue Count:", message.dequeueCount);
176  console.log("Pop Receipt:", message.popReceipt);
177  
178  // Process the message...
179  
180  // Delete after processing
181  await queueClient.deleteMessage(message.messageId, message.popReceipt);
182}
183```
184 
185### Peek Messages
186 
187Peek without removing from queue (no visibility timeout).
188 
189```typescript
190const response = await queueClient.peekMessages({
191  numberOfMessages: 5,
192});
193 
194for (const message of response.peekedMessageItems) {
195  console.log("Message ID:", message.messageId);
196  console.log("Content:", message.messageText);
197  // Note: No popReceipt - cannot delete peeked messages
198}
199```
200 
201### Update Message
202 
203Extend visibility timeout or update content.
204 
205```typescript
206// Receive a message
207const response = await queueClient.receiveMessages();
208const message = response.receivedMessageItems[0];
209 
210if (message) {
211  // Update content and extend visibility
212  const updateResponse = await queueClient.updateMessage(
213    message.messageId,
214    message.popReceipt,
215    "Updated content",
216    60 // New visibility timeout in seconds
217  );
218  
219  // Use new popReceipt for subsequent operations
220  console.log("New pop receipt:", updateResponse.popReceipt);
221}
222```
223 
224### Delete Message
225 
226```typescript
227// After receiving
228const response = await queueClient.receiveMessages();
229const message = response.receivedMessageItems[0];
230 
231if (message) {
232  await queueClient.deleteMessage(message.messageId, message.popReceipt);
233}
234```
235 
236### Clear All Messages
237 
238```typescript
239await queueClient.clearMessages();
240```
241 
242## Message Processing Patterns
243 
244### Basic Worker Pattern
245 
246```typescript
247async function processQueue(queueClient: QueueClient): Promise<void> {
248  while (true) {
249    const response = await queueClient.receiveMessages({
250      numberOfMessages: 10,
251      visibilityTimeout: 30,
252    });
253 
254    if (response.receivedMessageItems.length === 0) {
255      // No messages, wait before polling again
256      await sleep(5000);
257      continue;
258    }
259 
260    for (const message of response.receivedMessageItems) {
261      try {
262        await processMessage(message.messageText);
263        await queueClient.deleteMessage(message.messageId, message.popReceipt);
264      } catch (error) {
265        console.error(`Failed to process message ${message.messageId}:`, error);
266        // Message will become visible again after timeout
267      }
268    }
269  }
270}
271 
272async function processMessage(content: string): Promise<void> {
273  const task = JSON.parse(content);
274  // Process task...
275}
276 
277function sleep(ms: number): Promise<void> {
278  return new Promise((resolve) => setTimeout(resolve, ms));
279}
280```
281 
282### Poison Message Handling
283 
284```typescript
285const MAX_DEQUEUE_COUNT = 5;
286 
287async function processWithPoisonHandling(
288  queueClient: QueueClient,
289  poisonQueueClient: QueueClient
290): Promise<void> {
291  const response = await queueClient.receiveMessages({
292    numberOfMessages: 10,
293    visibilityTimeout: 30,
294  });
295 
296  for (const message of response.receivedMessageItems) {
297    if (message.dequeueCount > MAX_DEQUEUE_COUNT) {
298      // Move to poison queue
299      await poisonQueueClient.sendMessage(message.messageText);
300      await queueClient.deleteMessage(message.messageId, message.popReceipt);
301      console.log(`Moved message ${message.messageId} to poison queue`);
302      continue;
303    }
304 
305    try {
306      await processMessage(message.messageText);
307      await queueClient.deleteMessage(message.messageId, message.popReceipt);
308    } catch (error) {
309      console.error(`Processing failed (attempt ${message.dequeueCount}):`, error);
310    }
311  }
312}
313```
314 
315### Batch Processing with Visibility Extension
316 
317```typescript
318async function processBatchWithExtension(queueClient: QueueClient): Promise<void> {
319  const response = await queueClient.receiveMessages({
320    numberOfMessages: 1,
321    visibilityTimeout: 60,
322  });
323 
324  const message = response.receivedMessageItems[0];
325  if (!message) return;
326 
327  let popReceipt = message.popReceipt;
328 
329  // Start visibility extension timer
330  const extensionInterval = setInterval(async () => {
331    try {
332      const updateResponse = await queueClient.updateMessage(
333        message.messageId,
334        popReceipt,
335        message.messageText,
336        60 // Extend by another 60 seconds
337      );
338      popReceipt = updateResponse.popReceipt;
339    } catch (error) {
340      console.error("Failed to extend visibility:", error);
341    }
342  }, 45000); // Extend every 45 seconds
343 
344  try {
345    await longRunningProcess(message.messageText);
346    await queueClient.deleteMessage(message.messageId, popReceipt);
347  } finally {
348    clearInterval(extensionInterval);
349  }
350}
351```
352 
353## Message Encoding
354 
355By default, messages are Base64 encoded. You can customize this:
356 
357```typescript
358import { QueueClient } from "@azure/storage-queue";
359 
360// Custom encoder/decoder for plain text
361const queueClient = new QueueClient(
362  `https://${accountName}.queue.core.windows.net/my-queue`,
363  credential,
364  {
365    messageEncoding: "text", // "base64" (default) or "text"
366  }
367);
368 
369// Or with custom encoder
370const customQueueClient = new QueueClient(
371  `https://${accountName}.queue.core.windows.net/my-queue`,
372  credential,
373  {
374    messageEncoding: {
375      encode: (message: string) => Buffer.from(message).toString("base64"),
376      decode: (message: string) => Buffer.from(message, "base64").toString(),
377    },
378  }
379);
380```
381 
382## SAS Token Generation (Node.js only)
383 
384### Generate Queue SAS
385 
386```typescript
387import {
388  QueueSASPermissions,
389  generateQueueSASQueryParameters,
390  StorageSharedKeyCredential,
391} from "@azure/storage-queue";
392 
393const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
394 
395const sasToken = generateQueueSASQueryParameters(
396  {
397    queueName: "my-queue",
398    permissions: QueueSASPermissions.parse("raup"), // read, add, update, process
399    startsOn: new Date(),
400    expiresOn: new Date(Date.now() + 3600 * 1000), // 1 hour
401  },
402  sharedKeyCredential
403).toString();
404 
405const sasUrl = `https://${accountName}.queue.core.windows.net/my-queue?${sasToken}`;
406```
407 
408### Generate Account SAS
409 
410```typescript
411import {
412  AccountSASPermissions,
413  AccountSASResourceTypes,
414  AccountSASServices,
415  generateAccountSASQueryParameters,
416} from "@azure/storage-queue";
417 
418const sasToken = generateAccountSASQueryParameters(
419  {
420    services: AccountSASServices.parse("q").toString(), // queue
421    resourceTypes: AccountSASResourceTypes.parse("sco").toString(),
422    permissions: AccountSASPermissions.parse("rwdlacupi"),
423    expiresOn: new Date(Date.now() + 24 * 3600 * 1000),
424  },
425  sharedKeyCredential
426).toString();
427```
428 
429## Error Handling
430 
431```typescript
432import { RestError } from "@azure/storage-queue";
433 
434try {
435  await queueClient.sendMessage("test");
436} catch (error) {
437  if (error instanceof RestError) {
438    switch (error.statusCode) {
439      case 404:
440        console.log("Queue not found");
441        break;
442      case 400:
443        console.log("Bad request - message too large or invalid");
444        break;
445      case 403:
446        console.log("Access denied");
447        break;
448      case 409:
449        console.log("Queue already exists or being deleted");
450        break;
451      default:
452        console.error(`Storage error ${error.statusCode}: ${error.message}`);
453    }
454  }
455  throw error;
456}
457```
458 
459## TypeScript Types Reference
460 
461```typescript
462import {
463  // Clients
464  QueueServiceClient,
465  QueueClient,
466 
467  // Authentication
468  StorageSharedKeyCredential,
469  AnonymousCredential,
470 
471  // SAS
472  QueueSASPermissions,
473  AccountSASPermissions,
474  AccountSASServices,
475  AccountSASResourceTypes,
476  generateQueueSASQueryParameters,
477  generateAccountSASQueryParameters,
478 
479  // Messages
480  DequeuedMessageItem,
481  PeekedMessageItem,
482  QueueSendMessageResponse,
483  QueueReceiveMessageResponse,
484  QueueUpdateMessageResponse,
485 
486  // Queue
487  QueueItem,
488  QueueGetPropertiesResponse,
489 
490  // Errors
491  RestError,
492} from "@azure/storage-queue";
493```
494 
495## Message Limits
496 
497| Limit | Value |
498|-------|-------|
499| Max message size | 64 KB |
500| Max visibility timeout | 7 days |
501| Max time-to-live | 7 days (or -1 for infinite) |
502| Max messages per receive | 32 |
503| Default visibility timeout | 30 seconds |
504 
505## Best Practices
506 
5071. **Use DefaultAzureCredential** — Prefer AAD over connection strings/keys
5082. **Always delete after processing** — Prevent duplicate processing
5093. **Handle poison messages** — Move failed messages to a dead-letter queue
5104. **Use appropriate visibility timeout** — Set based on expected processing time
5115. **Extend visibility for long tasks** — Update message to prevent timeout
5126. **Use JSON for structured data** — Serialize objects to JSON strings
5137. **Check dequeueCount** — Detect repeatedly failing messages
5148. **Use batch receive** — Receive multiple messages for efficiency
515 
516## Platform Differences
517 
518| Feature | Node.js | Browser |
519|---------|---------|---------|
520| `StorageSharedKeyCredential` | ✅ | ❌ |
521| SAS generation | ✅ | ❌ |
522| DefaultAzureCredential | ✅ | ❌ |
523| Anonymous/SAS access | ✅ | ✅ |
524| All message operations | ✅ | ✅ |
525