@ayepi/aws 0.3.0 → 0.4.0

package/ayepi-aws.md

@@ -166,6 +166,7 @@ The returned [`Queue`](./ayepi-work-ports.md#queue--the-durable-work-log) maps o
 | `heartbeat(pulled, visibility)` | `ChangeMessageVisibility` | extends the lease to `ceil(visibility/1000)` s, **clamped to ≤ 43200 s** |
 | `ack(pulled)` | `DeleteMessage` | permanently removes the message (+ deletes the offloaded S3 body) |
 | `fail(pulled, delay?)` | `ChangeMessageVisibility` | returns the message early: `VisibilityTimeout` = `ceil((delay ?? 0)/1000)` s, **clamped to ≤ 43200 s** |
+| `size()` | `GetQueueAttributes` | reads `ApproximateNumberOfMessages` and returns it as a number (`0` when absent) |
 
 **SQS range clamping (far-future scheduling).** SQS rejects out-of-range values, so the queue
 clamps each duration into SQS's allowed range: `DelaySeconds` to **0–900 s** (15 min) on `push`,
@@ -184,6 +185,11 @@ horizons or keep distant schedules sparse.
   `max`. Each `PulledWork.attempt` comes from the message's `ApproximateReceiveCount` (delivery
   count, starting at 1); `handle` is an opaque `{ receiptHandle, s3Key? }` you round-trip to
   `heartbeat`/`ack`/`fail`.
+- **`size`** implements the optional `Queue.size()` — a single `GetQueueAttributes` reading
+  `ApproximateNumberOfMessages` (returned as a number, `0` when the attribute is absent, wrapped in
+  `retry` like every other call). It's what lets `@ayepi/work`'s sustained-backlog alarm
+  (`createWork({ onBacklog })`) report real SQS queue depth (`queued`). The count is **approximate**
+  — it's SQS's own `ApproximateNumberOfMessages`, not an exact tally.
 - **Dead-lettering** is the queue's own SQS **redrive policy** — configured on the queue (or its
   DLQ) in AWS, not here. After `maxReceiveCount` failed deliveries SQS moves the message to the
   DLQ natively. (`sqsQueue` does not implement the optional `Queue.deadLetter` hook.)

package/dist/sqs.cjs

@@ -128,6 +128,13 @@ function sqsQueue(opts) {
 				ReceiptHandle: handleOf(pulled).receiptHandle,
 				VisibilityTimeout: visSecs(delay ?? 0)
 			}));
+		}),
+		size: () => run(async () => {
+			const out = await client.send(new _aws_sdk_client_sqs.GetQueueAttributesCommand({
+				QueueUrl: queueUrl,
+				AttributeNames: ["ApproximateNumberOfMessages"]
+			}));
+			return Number(out.Attributes?.ApproximateNumberOfMessages ?? "0");
 		})
 	};
 }

package/dist/sqs.js

@@ -1,6 +1,6 @@
 import { makeRun } from "./index.js";
 import { randomUUID } from "node:crypto";
-import { ChangeMessageVisibilityCommand, DeleteMessageCommand, ReceiveMessageCommand, SendMessageCommand } from "@aws-sdk/client-sqs";
+import { ChangeMessageVisibilityCommand, DeleteMessageCommand, GetQueueAttributesCommand, ReceiveMessageCommand, SendMessageCommand } from "@aws-sdk/client-sqs";
 //#region src/sqs.ts
 /**
 * # @ayepi/aws/sqs — an SQS-backed `@ayepi/work` {@link Queue}
@@ -127,6 +127,13 @@ function sqsQueue(opts) {
 				ReceiptHandle: handleOf(pulled).receiptHandle,
 				VisibilityTimeout: visSecs(delay ?? 0)
 			}));
+		}),
+		size: () => run(async () => {
+			const out = await client.send(new GetQueueAttributesCommand({
+				QueueUrl: queueUrl,
+				AttributeNames: ["ApproximateNumberOfMessages"]
+			}));
+			return Number(out.Attributes?.ApproximateNumberOfMessages ?? "0");
 		})
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ayepi/aws",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "AWS backends for ayepi — an SQS @ayepi/work queue (large payloads offloaded to S3) and an S3 @ayepi/files store, all retry-wrapped for throttle resilience",
   "license": "MIT",
   "publishConfig": {
@@ -73,9 +73,9 @@
     "@aws-sdk/lib-storage": "^3",
     "@aws-sdk/s3-request-presigner": "^3",
     "@smithy/node-http-handler": "^4",
-    "@ayepi/core": "^0.3.0",
-    "@ayepi/work": "^0.3.0",
-    "@ayepi/files": "^0.3.0"
+    "@ayepi/core": "^0.4.0",
+    "@ayepi/work": "^0.4.0",
+    "@ayepi/files": "^0.4.0"
   },
   "peerDependenciesMeta": {
     "@ayepi/work": {
@@ -112,9 +112,9 @@
     "tsdown": "^0.12.0",
     "vitest": "^2.1.8",
     "zod": "^4.4.3",
-    "@ayepi/core": "0.3.0",
-    "@ayepi/files": "0.3.0",
-    "@ayepi/work": "0.3.0"
+    "@ayepi/core": "0.4.0",
+    "@ayepi/files": "0.4.0",
+    "@ayepi/work": "0.4.0"
   },
   "keywords": [
     "ayepi",