Doc updates (#13)

* Doc updates

* Fixes

Author: huntharo

README.md

@@ -6,6 +6,92 @@
 
 DynamoDB is an excellent choice for session stores because it is a fully managed service that is highly available, durable, and can scale automatically (to nearly unlimited levels) to meet demand. DynamoDB reads will typically return in 1-3 ms if capacity is set correctly and the caller is located in the same region as the `Table`.
 
+# Getting Started
+
+## Installation
+
+The package is available on npm as [@pwrdrvr/dynamodb-session-store](https://www.npmjs.com/package/@pwrdrvr/dynamodb-session-store)
+
+`npm i @pwrdrvr/dynamodb-session-store`
+
+## Importing
+
+```typescript
+import { DynamoDBStore } from '@pwrdrvr/dynamodb-session-store';
+```
+
+## Necessary IAM Policy
+
+The following IAM permissions are required for the DynamoDB Table:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Sid": "AllowDynamoDBAccess",
+      "Effect": "Allow",
+      "Action": [
+        "dynamodb:DescribeTable",
+        "dynamodb:GetItem",
+        "dynamodb:UpdateItem",
+        "dynamodb:PutItem",
+        "dynamodb:DeleteItem"
+      ],
+      "Resource": "arn:aws:dynamodb:us-east-1:123456789012:table/dynamodb-session-store-test"
+    }
+  ]
+}
+```
+
+## Example Usage
+
+[See the examples directory for more examples](./examples)
+
+```typescript
+import express from 'express';
+import session from 'express-session';
+import { DynamoDBStore } from '@pwrdrvr/dynamodb-session-store';
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+
+const app = express();
+const dynamoDBClient = new DynamoDBClient({});
+
+app.use(
+  session({
+    store: new DynamoDBStore({
+      tableName: 'some-table',
+      dynamoDBClient,
+      touchAfter: 60 * 60, // 60 minutes in seconds
+    }),
+    secret: 'yeah-change-this',
+    cookie: {
+      maxAge: 14 * 24 * 60 * 60 * 1000, // 14 days in milliseconds
+    },
+    resave: false,
+    saveUninitialized: false,
+  }),
+);
+
+app.get('/login', (req, res) => {
+  console.log(`Session ID: ${req.session?.id}`);
+  req.session.user = 'test';
+  res.send('Logged in');
+});
+
+app.get('/*', (req, res) => {
+  res.status(200).send('Hello world');
+});
+
+app.listen(Number.parseInt(PORT, 10), () => {
+  console.log(`Example app listening on port ${port}`);
+});
+```
+
+## API Documentation
+
+After installing the package review the [API Documentation](https://pwrdrvr.github.io/dynamodb-session-store/classes/DynamoDBStore.html) for detailed on each configuration option.
+
 # Features
 
 - Configurability of `Strongly Consistent Reads`
@@ -23,8 +109,8 @@ DynamoDB is an excellent choice for session stores because it is a fully managed
 
 # Configuration Tips
 
-- Use a Table per-region if you are deployed in multiple regions
-- Use a Table per-environment if you are deployed in multiple environments (e.g. dev/qa/prod)
+- Use a Table per-region if the app is deployed in multiple regions
+- Use a Table per-environment if the app is deployed in multiple environments (e.g. dev/qa/prod)
 - Use a Table unique to the session store - do not try to overload other data into this Table as the scaling and expiration needs will not overlap well
 - For applications attached to a VPC (including Lambda's attached to a VPC), use a VPC Endpoint for DynamoDB to avoid the cost, latency, and additional reliability exposure of crossing NAT Gateway to reach DynamoDB
 - Use Provisioned Capacity with auto-scaling to avoid throttling and to achieve the lowest cost - On Demand seems nice but it is costly

src/dynamodb-store.ts

@@ -80,9 +80,11 @@ export interface DynamoDBStoreOptions {
   /**
    * Create the DynamoDB table if it does not exist with OnDemand capacity
    *
-   * NOT SUGGESTED: this can create the table in many accounts and regions
+   * @remarks
+   *
+   * ⛔️ NOT SUGGESTED ⛔️: this can create the table in many accounts and regions
    * for any developer running the app locally with AWS credentials that
-   * have permission to create tables.  This is also a bad idea
+   * have permission to create tables. This is also a bad idea
    * because the least expensive option for relatively stable loads
    * is to use ProvisionedCapacity with Application Auto Scaling
    * configured to adjust the Read and Write capacity.
@@ -95,6 +97,9 @@ export interface DynamoDBStoreOptions {
   readonly createTableOptions?: Partial<CreateTableCommandInput>;
 
   /**
+   * Use Strongly Consistent Reads for session reads
+   *
+   * @remarks
    * Strongly Consistent Reads should rarely be needed for a session store unless
    * the values in the session are updated frequently and they must absolutely
    * be the most recent version (which is very unliley as the most recent
@@ -217,7 +222,7 @@ export class DynamoDBStore extends session.Store {
    * Enable TTL field on the table if configured
    *
    * @remarks
-   * This is not recommended for production use.
+   * ⛔️ NOT SUGGESTED ⛔️: This is not recommended for production use.
    *
    * For production the table should be created with IaaC (infrastructure as code)
    * such as AWS CDK, SAM, CloudFormation, Terraform, etc.
@@ -308,15 +313,14 @@ export class DynamoDBStore extends session.Store {
   }
 
   /**
-   * Create a DynamoDB Table-based express-session store.
-   *
-   * Note: This does not await creation of a table (which should only
-   * be used in quick and dirty tests).
-   *
-   * @param options DynamoDBStore options
+   * Create a DynamoDB Table-based [express-session](https://www.npmjs.com/package/express-session) store.
    *
    * @remarks
-   * `createTableOptions` is not recommended for production use.
+   * ⛔️ NOT SUGGESTED ⛔️: `createTableOptions` is not recommended for production use.
+   *
+   * Note: This does not await creation of a table if `createTableOptions` is passed (which should only
+   * be used in quick and dirty tests).  Use `DynamoDBStore.create()` instead to await
+   * creation of the table in testing scenarios.
    */
   constructor(options: DynamoDBStoreOptions) {
     super();