sqs-producer - npm Package Compare versions

Comparing version 4.0.0 to 5.0.0

dist/format.d.ts

 import { SendMessageBatchRequestEntry } from '@aws-sdk/client-sqs';
 import { Message } from './types';
+/**
+ * Converts a message to a SendMessageBatchRequestEntry using the appropriate method
+ * depending on if the message is a string or an object
+ * @param message The message to convert
+ */
 export declare function toEntry(message: string | Message): SendMessageBatchRequestEntry;

dist/format.js

@@ -5,2 +5,8 @@ "use strict";
 const validation_1 = require("./validation");
+/**
+ * Converts a message object to a SendMessageBatchRequestEntry
+ * @param message - The message to convert
+ * @returns The SendMessageBatchRequestEntry
+ * @throws Will throw an error if the message is invalid
+ */
 function entryFromObject(message) {
@@ -54,2 +60,6 @@ if (!message.body) {
 }
+/**
+ * Converts a message string to a SendMessageBatchRequestEntry
+ * @param message The message to convert
+ */
 function entryFromString(message) {
@@ -61,2 +71,7 @@ return {
 }
+/**
+ * Converts a message to a SendMessageBatchRequestEntry using the appropriate method
+ * depending on if the message is a string or an object
+ * @param message The message to convert
+ */
 function toEntry(message) {
@@ -63,0 +78,0 @@ if ((0, validation_1.isString)(message)) {

dist/producer.d.ts

 import { SQSClient, SendMessageBatchResultEntry } from '@aws-sdk/client-sqs';
 import { Message, ProducerOptions } from './types';
+/**
+ * [Usage](https://bbc.github.io/sqs-producer/index.html#usage)
+ */
 export declare class Producer {
@@ -10,6 +13,29 @@ static create: (options: ProducerOptions) => Producer;
     constructor(options: ProducerOptions);
+    /**
+     * Returns the number of messages in the queue.
+     * @returns A promise that resolves to the number of messages in the queue.
+     */
     queueSize(): Promise<number>;
+    /**
+     * Send a message to the queue.
+     * @param messages - A single message or an array of messages.
+     * @returns A promise that resolves to the result of the send operation.
+     */
     send(messages: string | Message | (string | Message)[]): Promise<SendMessageBatchResultEntry[]>;
+    /**
+     * Validate the producer options.
+     * @param options - The producer options to validate.
+     * @throws Error if any required options are missing or invalid.
+     */
     private validate;
+    /**
+     * Send a batch of messages to the queue.
+     * @param failedMessages - An array of failed message IDs.
+     * @param successfulMessages - An array of successful message results.
+     * @param messages - An array of messages to send.
+     * @param startIndex - The index of the first message in the batch.
+     * @returns A promise that resolves to the result of the send operation.
+     * @throws FailedMessagesError
+     */
     private sendBatch;
 }

dist/producer.js

@@ -6,5 +6,10 @@ "use strict";
 const format_1 = require("./format");
+const errors_1 = require("./errors");
 const requiredOptions = ['queueUrl'];
+/**
+ * [Usage](https://bbc.github.io/sqs-producer/index.html#usage)
+ */
 class Producer {
     constructor(options) {
+        var _a;
         this.validate(options);
@@ -15,4 +20,8 @@ this.queueUrl = options.queueUrl;
             options.sqs ||
-                new client_sqs_1.SQSClient(Object.assign(Object.assign({}, options), { region: options.region || process.env.AWS_REGION || 'eu-west-1' }));
+                new client_sqs_1.SQSClient(Object.assign(Object.assign({}, options), { useQueueUrlAsEndpoint: (_a = options.useQueueUrlAsEndpoint) !== null && _a !== void 0 ? _a : true, region: options.region || process.env.AWS_REGION || 'eu-west-1' }));
     }
+    /**
+     * Returns the number of messages in the queue.
+     * @returns A promise that resolves to the number of messages in the queue.
+     */
     async queueSize() {
@@ -28,2 +37,7 @@ const command = new client_sqs_1.GetQueueAttributesCommand({
     }
+    /**
+     * Send a message to the queue.
+     * @param messages - A single message or an array of messages.
+     * @returns A promise that resolves to the result of the send operation.
+     */
     async send(messages) {
@@ -36,2 +50,7 @@ const failedMessages = [];
     }
+    /**
+     * Validate the producer options.
+     * @param options - The producer options to validate.
+     * @throws Error if any required options are missing or invalid.
+     */
     validate(options) {
@@ -47,2 +66,11 @@ for (const option of requiredOptions) {
     }
+    /**
+     * Send a batch of messages to the queue.
+     * @param failedMessages - An array of failed message IDs.
+     * @param successfulMessages - An array of successful message results.
+     * @param messages - An array of messages to send.
+     * @param startIndex - The index of the first message in the batch.
+     * @returns A promise that resolves to the result of the send operation.
+     * @throws FailedMessagesError
+     */
     async sendBatch(failedMessages, successfulMessages, messages, startIndex) {
@@ -66,8 +94,12 @@ var _a;
         }
-        throw new Error(`Failed to send messages: ${failedMessagesBatch.join(', ')}`);
+        throw new errors_1.FailedMessagesError(failedMessagesBatch);
     }
 }
 exports.Producer = Producer;
+/**
+ * Creates a new producer.
+ * @param options - The producer options.
+ */
 Producer.create = (options) => {
     return new Producer(options);
 };

dist/types.d.ts

 import { MessageAttributeValue, SQSClient } from '@aws-sdk/client-sqs';
 export interface ProducerOptions {
+    /**
+     * The URL of the queue to send messages to.
+     */
     queueUrl: string;
+    /**
+     * The number of messages to send in a single batch.
+     */
     batchSize?: number;
+    /**
+     * The SQS client to use. If not provided, a new client will be created.
+     */
     sqs?: SQSClient;
+    /**
+     * The AWS region to use. If not provided, the region will be determined
+     * from the `AWS_REGION` environment variable or will default to `eu-west-1.
+     */
     region?: string;
+    /**
+     * In cases where a QueueUrl is given as input, that
+     * will be preferred as the request endpoint.
+     *
+     * Set this value to false to ignore the QueueUrl and use the
+     * client's resolved endpoint, which may be a custom endpoint.
+     */
+    useQueueUrlAsEndpoint?: boolean;
 }
 export interface Message {
+    /**
+     * An identifier for the message. This must be unique within
+     * the batch of messages.
+     */
     id: string;
+    /**
+     * The messages contents.
+     */
     body: string;
+    /**
+     * This parameter applies only to FIFO (first-in-first-out) queues.
+     * When set messages that belong to the same message group are processed
+     * in a FIFO manner
+     */
     groupId?: string;
+    /**
+     * This parameter applies only to FIFO (first-in-first-out) queues.
+     * The token used for deduplication of messages within a 5-minute minimum
+     * deduplication interval. If a message with a particular id is sent successfully,
+     * subsequent messages with the same id are accepted
+     * successfully but aren't delivered.
+     */
     deduplicationId?: string;
+    /**
+     * The length of time, in seconds, for which to delay a specific message.
+     * Valid values: 0 to 900. Maximum: 15 minutes.
+     */
     delaySeconds?: number;
+    /**
+     * Each message attribute consists of a Name, Type, and Value. For more
+     * information, see [Amazon SQS message attributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-attributes.html).
+     */
     messageAttributes?: {
@@ -15,0 +63,0 @@ [key: string]: MessageAttributeValue;

dist/validation.d.ts

@@ -0,3 +1,15 @@
+/**
+ * Checks if the value is a string
+ * @param value - The value to check
+ */
 export declare function isString(value: any): boolean;
+/**
+ * Checks if the value is an object
+ * @param value - The value to check
+ */
 export declare function isObject(value: any): boolean;
+/**
+ * Checks if a MessageAttribute is valid
+ * @param messageAttribute - The MessageAttribute to check
+ */
 export declare function isMessageAttributeValid(messageAttribute: any): boolean;

dist/validation.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isMessageAttributeValid = exports.isObject = exports.isString = void 0;
+/**
+ * Checks if the value is a string
+ * @param value - The value to check
+ */
 function isString(value) {
@@ -8,2 +12,6 @@ return typeof value === 'string' || value instanceof String;
 exports.isString = isString;
+/**
+ * Checks if the value is an object
+ * @param value - The value to check
+ */
 function isObject(value) {
@@ -13,2 +21,6 @@ return value && typeof value === 'object' && value instanceof Object;
 exports.isObject = isObject;
+/**
+ * Checks if a MessageAttribute is valid
+ * @param messageAttribute - The MessageAttribute to check
+ */
 function isMessageAttributeValid(messageAttribute) {
@@ -15,0 +27,0 @@ if (!messageAttribute.DataType) {

package.json

 {
   "name": "sqs-producer",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "Enqueues messages onto a given SQS queue",
@@ -14,3 +14,3 @@ "main": "dist/index.js",
     "lint:fix": "eslint . --fix",
-    "format": "prettier --loglevel warn --write \"**/*.{js,json,jsx,md,ts,tsx,html}\"",
+    "format": "prettier --log-level warn --write \"**/*.{js,json,jsx,md,ts,tsx,html}\"",
     "format:check": "prettier --check \"**/*.{js,json,jsx,md,ts,tsx,html}\"",
@@ -21,3 +21,4 @@ "build": "npm run clean && tsc",
     "watch": "tsc --watch",
-    "clean": "rm -fr dist/*"
+    "clean": "rm -fr dist/*",
+    "generate-docs": "typedoc"
   },
@@ -41,25 +42,121 @@ "engines": {
   ],
-  "homepage": "https://github.com/bbc/sqs-producer",
+  "homepage": "https://bbc.github.io/sqs-producer/",
+  "publishConfig": {
+    "provenance": true
+  },
+  "release": {
+    "branches": [
+      "main",
+      {
+        "name": "canary",
+        "prerelease": true
+      }
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "conventionalcommits",
+          "releaseRules": [
+            {
+              "type": "breaking",
+              "release": "major"
+            },
+            {
+              "type": "feat",
+              "release": "minor"
+            },
+            {
+              "type": "chore",
+              "release": "patch"
+            },
+            {
+              "type": "fix",
+              "release": "patch"
+            },
+            {
+              "type": "docs",
+              "release": "patch"
+            },
+            {
+              "type": "refactor",
+              "release": "patch"
+            },
+            {
+              "type": "test",
+              "release": "patch"
+            }
+          ]
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "conventionalcommits",
+          "presetConfig": {
+            "types": [
+              {
+                "type": "feat",
+                "section": "Features"
+              },
+              {
+                "type": "fix",
+                "section": "Bug Fixes"
+              },
+              {
+                "type": "chore",
+                "section": "Chores"
+              },
+              {
+                "type": "docs",
+                "section": "Documentation"
+              },
+              {
+                "type": "refactor",
+                "section": "Refactors"
+              },
+              {
+                "type": "test",
+                "section": "Tests"
+              }
+            ]
+          }
+        }
+      ],
+      "@semantic-release/changelog",
+      "@semantic-release/github",
+      "@semantic-release/npm"
+    ]
+  },
   "devDependencies": {
-    "@types/chai": "^4.3.9",
-    "@types/debug": "^4.1.10",
-    "@types/mocha": "^10.0.3",
-    "@types/node": "^20.8.7",
-    "@types/sinon": "^10.0.20",
-    "chai": "^4.3.10",
-    "eslint": "^8.52.0",
-    "eslint-config-iplayer": "^9.1.0",
-    "eslint-config-prettier": "^9.0.0",
-    "mocha": "^10.2.0",
-    "c8": "^8.0.1",
-    "prettier": "^3.0.3",
-    "sinon": "^17.0.0",
-    "ts-node": "^10.9.1",
-    "typescript": "^5.2.2"
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^11.1.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^9.2.6",
+    "@semantic-release/npm": "11.0.2",
+    "@semantic-release/release-notes-generator": "^12.1.0",
+    "@types/chai": "^4.3.12",
+    "@types/debug": "^4.1.12",
+    "@types/mocha": "^10.0.6",
+    "@types/node": "^20.11.25",
+    "@types/sinon": "^17.0.3",
+    "chai": "^4.4.1",
+    "conventional-changelog-conventionalcommits": "^7.0.2",
+    "eslint": "^8.57.0",
+    "eslint-config-iplayer": "^9.2.0",
+    "eslint-config-prettier": "^9.1.0",
+    "mocha": "^10.3.0",
+    "c8": "^9.1.0",
+    "prettier": "^3.2.5",
+    "semantic-release": "^23.0.0",
+    "sinon": "^17.0.1",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.25.12",
+    "typescript": "^5.4.2"
   },
   "dependencies": {
-    "@aws-sdk/client-sqs": "^3.454.0"
+    "@aws-sdk/client-sqs": "^3.529.1"
   },
   "peerDependencies": {
-    "@aws-sdk/client-sqs": "^3.454.0"
+    "@aws-sdk/client-sqs": "^3.529.1"
   },
@@ -66,0 +163,0 @@ "mocha": {

README.md

@@ -8,6 +8,8 @@ # sqs-producer
 
-Enqueues messages onto a given SQS queue
+Enqueues messages onto a given SQS queue.
 
 ## Installation
 
+To install this package, enter the following command into your terminal (or the variant of whatever package manager you are using):
+
 ```
@@ -28,2 +30,6 @@ npm install sqs-producer
 
+## Documentation
+
+Visit [https://bbc.github.io/sqs-producer/](https://bbc.github.io/sqs-producer/) for the full API documentation.
+
 ## Usage
@@ -83,3 +89,3 @@
 //
-// http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queue-recommendations.html
+// https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queue-recommendations.html
 await producer.send({
@@ -95,3 +101,3 @@ id: 'testId',
 
-By default the consumer will look for AWS credentials in the places [specified by the AWS SDK](http://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html#Setting_AWS_Credentials). The simplest option is to export your credentials as environment variables:
+By default the consumer will look for AWS credentials in the places [specified by the AWS SDK](https://docs.aws.amazon.com/AWSJavaScriptSDK/guide/node-configuring.html#Setting_AWS_Credentials). The simplest option is to export your credentials as environment variables:
 
@@ -130,3 +136,3 @@ ```bash
 
-```
+```bash
 npm test
@@ -139,3 +145,3 @@ ```
 
-```
+```bash
 npm run coverage
@@ -148,3 +154,3 @@ ```
 
-```
+```bash
 npm run lint
@@ -155,2 +161,8 @@ ```
 
-See [contributing guildlines](./.github/CONTRIBUTING.md)
+We welcome and appreciate contributions for anyone who would like to take the time to fix a bug or implement a new feature.
+
+But before you get started, [please read the contributing guidelines](https://github.com/bbc/sqs-producer/blob/main/.github/CONTRIBUTING.md) and [code of conduct](https://github.com/bbc/sqs-producer/blob/main/.github/CODE_OF_CONDUCT.md).
+
+## License
+
+SQS Producer is distributed under the Apache License, Version 2.0, see [LICENSE](./LICENSE) for more information.

src/format.ts

@@ -5,2 +5,8 @@ import { SendMessageBatchRequestEntry } from '@aws-sdk/client-sqs';
 
+/**
+ * Converts a message object to a SendMessageBatchRequestEntry
+ * @param message - The message to convert
+ * @returns The SendMessageBatchRequestEntry
+ * @throws Will throw an error if the message is invalid
+ */
 function entryFromObject(message: Message): SendMessageBatchRequestEntry {
@@ -73,2 +79,6 @@ if (!message.body) {
 
+/**
+ * Converts a message string to a SendMessageBatchRequestEntry
+ * @param message The message to convert
+ */
 function entryFromString(message: string): SendMessageBatchRequestEntry {
@@ -81,2 +91,7 @@ return {
 
+/**
+ * Converts a message to a SendMessageBatchRequestEntry using the appropriate method
+ * depending on if the message is a string or an object
+ * @param message The message to convert
+ */
 export function toEntry(
@@ -83,0 +98,0 @@ message: string | Message

src/producer.ts

@@ -9,5 +9,9 @@ import {
 import { toEntry } from './format';
+import { FailedMessagesError } from './errors';
 
 const requiredOptions = ['queueUrl'];
 
+/**
+ * [Usage](https://bbc.github.io/sqs-producer/index.html#usage)
+ */
 export class Producer {
@@ -28,2 +32,3 @@ static create: (options: ProducerOptions) => Producer;
         ...options,
+        useQueueUrlAsEndpoint: options.useQueueUrlAsEndpoint ?? true,
         region: options.region || process.env.AWS_REGION || 'eu-west-1'
@@ -33,2 +38,6 @@ });
 
+  /**
+   * Returns the number of messages in the queue.
+   * @returns A promise that resolves to the number of messages in the queue.
+   */
   async queueSize(): Promise<number> {
@@ -49,2 +58,7 @@ const command = new GetQueueAttributesCommand({
 
+  /**
+   * Send a message to the queue.
+   * @param messages - A single message or an array of messages.
+   * @returns A promise that resolves to the result of the send operation.
+   */
   async send(
@@ -66,2 +80,7 @@ messages: string | Message | (string | Message)[]
 
+  /**
+   * Validate the producer options.
+   * @param options - The producer options to validate.
+   * @throws Error if any required options are missing or invalid.
+   */
   private validate(options: ProducerOptions): void {
@@ -78,2 +97,11 @@ for (const option of requiredOptions) {
 
+  /**
+   * Send a batch of messages to the queue.
+   * @param failedMessages - An array of failed message IDs.
+   * @param successfulMessages - An array of successful message results.
+   * @param messages - An array of messages to send.
+   * @param startIndex - The index of the first message in the batch.
+   * @returns A promise that resolves to the result of the send operation.
+   * @throws FailedMessagesError
+   */
   private async sendBatch(
@@ -113,10 +141,12 @@ failedMessages?: string[],
     }
-    throw new Error(
-      `Failed to send messages: ${failedMessagesBatch.join(', ')}`
-    );
+    throw new FailedMessagesError(failedMessagesBatch);
   }
 }
 
+/**
+ * Creates a new producer.
+ * @param options - The producer options.
+ */
 Producer.create = (options: ProducerOptions): Producer => {
   return new Producer(options);
 };

src/types.ts

 import { MessageAttributeValue, SQSClient } from '@aws-sdk/client-sqs';
 
 export interface ProducerOptions {
+  /**
+   * The URL of the queue to send messages to.
+   */
   queueUrl: string;
+  /**
+   * The number of messages to send in a single batch.
+   */
   batchSize?: number;
+  /**
+   * The SQS client to use. If not provided, a new client will be created.
+   */
   sqs?: SQSClient;
+  /**
+   * The AWS region to use. If not provided, the region will be determined
+   * from the `AWS_REGION` environment variable or will default to `eu-west-1.
+   */
   region?: string;
+  /**
+   * In cases where a QueueUrl is given as input, that
+   * will be preferred as the request endpoint.
+   *
+   * Set this value to false to ignore the QueueUrl and use the
+   * client's resolved endpoint, which may be a custom endpoint.
+   */
+  useQueueUrlAsEndpoint?: boolean;
 }
 
 export interface Message {
+  /**
+   * An identifier for the message. This must be unique within
+   * the batch of messages.
+   */
   id: string;
+  /**
+   * The messages contents.
+   */
   body: string;
+  /**
+   * This parameter applies only to FIFO (first-in-first-out) queues.
+   * When set messages that belong to the same message group are processed
+   * in a FIFO manner
+   */
   groupId?: string;
+  /**
+   * This parameter applies only to FIFO (first-in-first-out) queues.
+   * The token used for deduplication of messages within a 5-minute minimum
+   * deduplication interval. If a message with a particular id is sent successfully,
+   * subsequent messages with the same id are accepted
+   * successfully but aren't delivered.
+   */
   deduplicationId?: string;
+  /**
+   * The length of time, in seconds, for which to delay a specific message.
+   * Valid values: 0 to 900. Maximum: 15 minutes.
+   */
   delaySeconds?: number;
+  /**
+   * Each message attribute consists of a Name, Type, and Value. For more
+   * information, see [Amazon SQS message attributes](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-message-attributes.html).
+   */
   messageAttributes?: { [key: string]: MessageAttributeValue };
 }

src/validation.ts

@@ -0,1 +1,5 @@
+/**
+ * Checks if the value is a string
+ * @param value - The value to check
+ */
 export function isString(value: any): boolean {
@@ -5,2 +9,6 @@ return typeof value === 'string' || value instanceof String;
 
+/**
+ * Checks if the value is an object
+ * @param value - The value to check
+ */
 export function isObject(value: any): boolean {
@@ -10,2 +18,6 @@ return value && typeof value === 'object' && value instanceof Object;
 
+/**
+ * Checks if a MessageAttribute is valid
+ * @param messageAttribute - The MessageAttribute to check
+ */
 export function isMessageAttributeValid(messageAttribute: any): boolean {
@@ -12,0 +24,0 @@ if (!messageAttribute.DataType) {

No alert changes

Improved metrics

Total package byte prevSize

61253

increased by43.09%

Number of package files

44

increased by25.71%

Lines of code

750

increased by70.07%

Number of lines in readme file

161

increased by8.05%

Worsened metrics

Dev dependency count

24

increased by60%

Dependency changes

• Updated@aws-sdk/client-sqs@^3.529.1