chore: add documentation

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18.x
+          cache: 'npm'
+
+      - name: NPM Audit
+        run: npx audit-ci
+
+      - name: Install Node Modules
+        run: npm ci
+
+      - name: Build Docs
+        run: npm run generate-docs
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: './public'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -4,3 +4,4 @@ dist
 .nyc_output
 .idea
 .DS_Store
+public

.npmignore

@@ -4,3 +4,4 @@ lib-cov
 coverage/
 .nyc_output/
 test
+public

.prettierignore

@@ -1,4 +1,5 @@
 node_modules
 coverage
 bake-scripts
-dist
+dist
+public

README.md

@@ -5,10 +5,12 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/5220635a4598c9f1a546/maintainability)](https://codeclimate.com/github/bbc/sqs-producer/maintainability)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/5220635a4598c9f1a546/test_coverage)](https://codeclimate.com/github/bbc/sqs-producer/test_coverage)
 
-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):
+
 ```
 npm install sqs-producer
 ```
@@ -24,6 +26,10 @@ npm install sqs-producer
 
 We will only support Node versions that are actively or security supported by the Node team. If you are still using an Node 14, please use a version of this library before the v3.2.1 release, if you are using Node 16, please use a version before the v3.3.0 release.
 
+## Documentation
+
+Visit [https://bbc.github.io/sqs-producer/](https://bbc.github.io/sqs-producer/) for the full API documentation.
+
 ## Usage
 
 ```js
@@ -78,7 +84,7 @@ await producer.send([
 //
 // deduplicationId can be excluded if content-based deduplication is enabled
 //
-// 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({
   id: 'testId',
   body: 'Hello world from our FIFO queue!',
@@ -89,7 +95,7 @@ await producer.send({
 
 ### Credentials
 
-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:
 
 ```bash
 export AWS_SECRET_ACCESS_KEY=...
@@ -123,26 +129,32 @@ await producer.send(['msg1', 'msg2']);
 
 ### Test
 
-```
+```bash
 npm test
 ```
 
 ### Coverage
 
 For coverage report, run the command:
 
-```
+```bash
 npm run coverage
 ```
 
 ### Lint
 
 To check for problems using ESLint
 
-```
+```bash
 npm run lint
 ```
 
 ## Contributing
 
-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.

package.json

@@ -17,7 +17,8 @@
     "prepublishOnly": "npm run build",
     "pretest": "npm run build",
     "watch": "tsc --watch",
-    "clean": "rm -fr dist/*"
+    "clean": "rm -fr dist/*",
+    "generate-docs": "typedoc"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -36,7 +37,7 @@
     "producer",
     "queue"
   ],
-  "homepage": "https://github.com/bbc/sqs-producer",
+  "homepage": "https://bbc.github.io/sqs-producer/",
   "devDependencies": {
     "@types/chai": "^4.3.12",
     "@types/debug": "^4.1.12",
@@ -52,6 +53,7 @@
     "prettier": "^3.2.5",
     "sinon": "^17.0.1",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.25.12",
     "typescript": "^5.4.2"
   },
   "dependencies": {

src/errors.ts

@@ -1,3 +1,6 @@
+/**
+ * Error thrown when a message fails to send.
+ */
 export class FailedMessagesError extends Error {
   /** Ids of messages that failed to send. */
   public failedMessages: string[];

src/format.ts

@@ -2,6 +2,12 @@ import { SendMessageBatchRequestEntry } from '@aws-sdk/client-sqs';
 import { Message } from './types';
 import { isObject, isString, isMessageAttributeValid } from './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: Message): SendMessageBatchRequestEntry {
   if (!message.body) {
     throw new Error(`Object messages must have 'body' prop`);
@@ -69,13 +75,22 @@ function entryFromObject(message: Message): SendMessageBatchRequestEntry {
   return entry;
 }
 
+/**
+ * Converts a message string to a SendMessageBatchRequestEntry
+ * @param message The message to convert
+ */
 function entryFromString(message: string): SendMessageBatchRequestEntry {
   return {
     Id: message,
     MessageBody: message
   };
 }
 
+/**
+ * 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(
   message: string | Message
 ): SendMessageBatchRequestEntry {