patch: added READMEs and Metrics package

evilkiwi · Mar 24, 2022 · a8371e5 · a8371e5
1 parent b5ef50b
commit a8371e5
Show file tree

Hide file tree

Showing 22 changed files with 606 additions and 9 deletions.
diff --git a/README.md b/README.md
@@ -31,8 +31,51 @@ yarn add @tnotifier/lamware
 npm install @tnotifier/lamware
 ```
 
-We maintain and ship various middlewares for public use - you can [install them too!](#TODO:)
+We maintain and ship various middlewares for public use - you can [install them too!](https://github.com/tnotifier/lamware/tree/master/packages)
 
 ## Usage
 
-You can check out the [`example` folder](#TODO:) for a fully-featured example.
+You can check out the [`example` folder](https://github.com/tnotifier/lamware/tree/master/example) for a fully-featured example with the AWS CDK stack to deploy it.
+
+```typescript
+import { powertoolsTracing } from '@tnotifier/lamware-powertools-tracing';
+import { powertoolsLogger } from '@tnotifier/lamware-powertools-logger';
+import type { APIGatewayProxyHandlerV2 } from 'aws-lambda';
+import { doNotWait } from '@tnotifier/lamware-do-not-wait';
+import { appconfig } from '@tnotifier/lamware-appconfig';
+import { sentry } from '@tnotifier/lamware-sentry';
+import { warmer } from '@tnotifier/lamware-warmer';
+import { lamware } from '@tnotifier/lamware';
+
+const { handler } = lamware<APIGatewayProxyHandlerV2<any>>()
+    .use(doNotWait())
+    .use(powertoolsTracing({
+        serviceName: 'lamware-example',
+    }))
+    .use(powertoolsLogger({
+        serviceName: 'lamware-example',
+        logLevel: 'DEBUG',
+    }))
+    .use(appconfig<{ hello: string }>({
+        app: 'tnotifier-lamware-example',
+        env: 'production',
+        config: 'production',
+    }))
+    .use(sentry({
+        config: {
+            dsn: 'https://[email protected]/6270000',
+        },
+    }))
+    .use(warmer())
+    .execute(async ({ state }) => {
+        return {
+            statusCode: 200,
+            body: JSON.stringify({
+                hello: 'world',
+                appconfig: state.config,
+            }),
+        };
+    });
+
+export { handler };
+```
diff --git a/packages/appconfig/README.md b/packages/appconfig/README.md
@@ -0,0 +1,60 @@
+<div align="center">
+    <a href="https://www.npmjs.com/package/@tnotifier/lamware-appconfig" target="_blank">
+        <img src="https://img.shields.io/npm/v/@tnotifier/lamware-appconfig?style=flat-square" alt="NPM" />
+    </a>
+    <a href="https://discord.gg/XMrHXtN" target="_blank">
+        <img src="https://img.shields.io/discord/123906549860139008?color=7289DA&label=discord&logo=discord&logoColor=FFFFFF&style=flat-square" alt="Discord" />
+    </a>
+    <img src="https://img.shields.io/npm/l/@tnotifier/lamware-appconfig?style=flat-square" alt="Apache-2.0" />
+    <h3>Lamware - AWS AppConfig</h3>
+</div>
+
+This [Lamware](https://github.com/tnotifier/lamware) Middleware utilizes an API exposed by the [AWS Lambda AppConfig Layer Extension](https://docs.aws.amazon.com/appconfig/latest/userguide/appconfig-integration-lambda-extensions.html) to pull-down a copy of an AppConfig configuration and allows you to easily provide TypeScript typings for it.
+
+## Installation
+
+This package is available via NPM:
+
+```bash
+yarn add @tnotifier/lamware-appconfig
+
+# or
+
+npm install @tnotifier/lamware-appconfig
+```
+
+## Usage
+
+```typescript
+import type { APIGatewayProxyHandlerV2 } from 'aws-lambda';
+import { appconfig } from '@tnotifier/lamware-appconfig';
+import { lamware } from '@tnotifier/lamware';
+
+interface AppConfig {
+    helloWorld: string;
+}
+
+const { handler } = lamware<APIGatewayProxyHandlerV2<any>>()
+    /**
+     * You can provide an Interface to the middleware to automatically type
+     * the config in the handler `execute`.
+     **/
+    .use(appconfig<AppConfig>({
+        // Ensure you provide the info required to pull down a configuration.
+        app: 'tnotifier-api',
+        env: 'production',
+        config: 'production',
+        // You can also optionally provide an override URL for the AppConfig API.
+        url: 'http://localhost:2772', // The default, provided by the AppConfig Lambda Extension.
+    }))
+    .execute(async ({ state }) => {
+        return {
+            statusCode: 200,
+            body: JSON.stringify({
+                debug: state.config.helloWorld,
+            }),
+        };
+    });
+
+export { handler };
+```
diff --git a/packages/appconfig/package.json b/packages/appconfig/package.json
@@ -12,7 +12,7 @@
     "license": "GPL-3.0-only",
     "author": {
         "name": "Evil Kiwi Limited",
-        "url": "https://tnotifier.app",
+        "url": "https://evil.kiwi",
         "email": "[email protected]"
     },
     "homepage": "https://github.com/tnotifier/lamware",

diff --git a/packages/core/README.md b/packages/core/README.md
@@ -0,0 +1,12 @@
+<div align="center">
+    <a href="https://www.npmjs.com/package/@tnotifier/lamware" target="_blank">
+        <img src="https://img.shields.io/npm/v/@tnotifier/lamware?style=flat-square" alt="NPM" />
+    </a>
+    <a href="https://discord.gg/XMrHXtN" target="_blank">
+        <img src="https://img.shields.io/discord/123906549860139008?color=7289DA&label=discord&logo=discord&logoColor=FFFFFF&style=flat-square" alt="Discord" />
+    </a>
+    <img src="https://img.shields.io/npm/l/@tnotifier/lamware?style=flat-square" alt="Apache-2.0" />
+    <h3>Lamware - Core Functionality</h3>
+</div>
+
+Refer to the [root README](https://github.com/tnotifier/lamware/blob/master/README.md).
diff --git a/packages/core/package.json b/packages/core/package.json
@@ -11,7 +11,7 @@
     "license": "GPL-3.0-only",
     "author": {
         "name": "Evil Kiwi Limited",
-        "url": "https://tnotifier.app",
+        "url": "https://evil.kiwi",
         "email": "[email protected]"
     },
     "homepage": "https://github.com/tnotifier/lamware",

diff --git a/packages/do-not-wait/README.md b/packages/do-not-wait/README.md
@@ -0,0 +1,40 @@
+<div align="center">
+    <a href="https://www.npmjs.com/package/@tnotifier/lamware-do-not-wait" target="_blank">
+        <img src="https://img.shields.io/npm/v/@tnotifier/lamware-do-not-wait?style=flat-square" alt="NPM" />
+    </a>
+    <a href="https://discord.gg/XMrHXtN" target="_blank">
+        <img src="https://img.shields.io/discord/123906549860139008?color=7289DA&label=discord&logo=discord&logoColor=FFFFFF&style=flat-square" alt="Discord" />
+    </a>
+    <img src="https://img.shields.io/npm/l/@tnotifier/lamware-do-not-wait?style=flat-square" alt="Apache-2.0" />
+    <h3>Lamware - Do Not Wait</h3>
+</div>
+
+This [Lamware](https://github.com/tnotifier/lamware) Middleware implements a Lambda best-practice of making sure Lambda doesn't wait for the event loop to be empty prior to responding by ensuring the `callbackWaitsForEmptyEventLoop` context variable is set to `false`.
+
+## Installation
+
+This package is available via NPM:
+
+```bash
+yarn add @tnotifier/lamware-do-not-wait
+
+# or
+
+npm install @tnotifier/lamware-do-not-wait
+```
+
+## Usage
+
+```typescript
+import type { APIGatewayProxyHandlerV2 } from 'aws-lambda';
+import { doNotWait } from '@tnotifier/lamware-do-not-wait';
+import { lamware } from '@tnotifier/lamware';
+
+const { handler } = lamware<APIGatewayProxyHandlerV2<any>>()
+    .use(doNotWait())
+    .execute(async () => {
+        return { statusCode: 200 };
+    });
+
+export { handler };
+```
diff --git a/packages/do-not-wait/package.json b/packages/do-not-wait/package.json
@@ -12,7 +12,7 @@
     "license": "GPL-3.0-only",
     "author": {
         "name": "Evil Kiwi Limited",
-        "url": "https://tnotifier.app",
+        "url": "https://evil.kiwi",
         "email": "[email protected]"
     },
     "homepage": "https://github.com/tnotifier/lamware",

diff --git a/packages/powertools-logger/README.md b/packages/powertools-logger/README.md
@@ -0,0 +1,49 @@
+<div align="center">
+    <a href="https://www.npmjs.com/package/@tnotifier/lamware-powertools-logger" target="_blank">
+        <img src="https://img.shields.io/npm/v/@tnotifier/lamware-powertools-logger?style=flat-square" alt="NPM" />
+    </a>
+    <a href="https://discord.gg/XMrHXtN" target="_blank">
+        <img src="https://img.shields.io/discord/123906549860139008?color=7289DA&label=discord&logo=discord&logoColor=FFFFFF&style=flat-square" alt="Discord" />
+    </a>
+    <img src="https://img.shields.io/npm/l/@tnotifier/lamware-powertools-logger?style=flat-square" alt="Apache-2.0" />
+    <h3>Lamware - AWS Powertools Logger</h3>
+</div>
+
+This [Lamware](https://github.com/tnotifier/lamware) Middleware utilizes the official [Lambda TypeScript Powertools](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/logger/) provided by AWS to:
+
+- Set-up and memoize a root `Logger` instance
+- Automatically add Lambda Context to all logging (can be disabled)
+- Provide a logging interface to all further middleware & the handler itself
+
+## Installation
+
+This package is available via NPM:
+
+```bash
+yarn add @tnotifier/lamware-powertools-logger
+
+# or
+
+npm install @tnotifier/lamware-powertools-logger
+```
+
+## Usage
+
+```typescript
+import { powertoolsLogger } from '@tnotifier/lamware-powertools-logger';
+import type { APIGatewayProxyHandlerV2 } from 'aws-lambda';
+import { lamware } from '@tnotifier/lamware';
+
+const { handler } = lamware<APIGatewayProxyHandlerV2<any>>()
+    .use(powertoolsLogger({
+        // Options are pass-through to the Logger instance.
+        serviceName: 'my-api',
+    }))
+    .execute(async ({ state, logger }) => {
+        logger.debug('Hello world!');
+
+        return { statusCode: 200 };
+    });
+
+export { handler };
+```
diff --git a/packages/powertools-logger/package.json b/packages/powertools-logger/package.json
@@ -12,7 +12,7 @@
     "license": "GPL-3.0-only",
     "author": {
         "name": "Evil Kiwi Limited",
-        "url": "https://tnotifier.app",
+        "url": "https://evil.kiwi",
         "email": "[email protected]"
     },
     "homepage": "https://github.com/tnotifier/lamware",

diff --git a/packages/powertools-metrics/.gitignore b/packages/powertools-metrics/.gitignore
@@ -0,0 +1 @@
+/build
diff --git a/packages/powertools-metrics/README.md b/packages/powertools-metrics/README.md
@@ -0,0 +1,54 @@
+<div align="center">
+    <a href="https://www.npmjs.com/package/@tnotifier/lamware-powertools-metrics" target="_blank">
+        <img src="https://img.shields.io/npm/v/@tnotifier/lamware-powertools-metrics?style=flat-square" alt="NPM" />
+    </a>
+    <a href="https://discord.gg/XMrHXtN" target="_blank">
+        <img src="https://img.shields.io/discord/123906549860139008?color=7289DA&label=discord&logo=discord&logoColor=FFFFFF&style=flat-square" alt="Discord" />
+    </a>
+    <img src="https://img.shields.io/npm/l/@tnotifier/lamware-powertools-metrics?style=flat-square" alt="Apache-2.0" />
+    <h3>Lamware - AWS Powertools Metrics</h3>
+</div>
+
+This [Lamware](https://github.com/tnotifier/lamware) Middleware utilizes the official [Lambda TypeScript Powertools](https://awslabs.github.io/aws-lambda-powertools-typescript/latest/core/metrics/) provided by AWS to:
+
+- Set-up and memoize a root `Metrics` instance
+- Publish Metrics automatically after the Function handler executes
+- Optionally set-up default dimensions
+- Automatically capture various metrics:
+  - Cold starts
+  - Function name
+
+## Installation
+
+This package is available via NPM:
+
+```bash
+yarn add @tnotifier/lamware-powertools-metrics
+
+# or
+
+npm install @tnotifier/lamware-powertools-metrics
+```
+
+## Usage
+
+```typescript
+import { powertoolsMetrics } from '@tnotifier/lamware-powertools-metrics';
+import { MetricUnits } from '@aws-lambda-powertools/metrics';
+import type { APIGatewayProxyHandlerV2 } from 'aws-lambda';
+import { lamware } from '@tnotifier/lamware';
+
+const { handler } = lamware<APIGatewayProxyHandlerV2<any>>()
+    .use(powertoolsMetrics({
+        // Options are pass-through to the Tracing instance.
+        namespace: 'tnotifier',
+        serviceName: 'my-api',
+    }))
+    .execute(async ({ state }) => {
+        state.metrics.addMetric('successfulBooking', MetricUnits.Count, 1);
+
+        return { statusCode: 200 };
+    });
+
+export { handler };
+```
diff --git a/packages/powertools-metrics/package.json b/packages/powertools-metrics/package.json
@@ -0,0 +1,55 @@
+{
+    "name": "@tnotifier/lamware-powertools-metrics",
+    "version": "1.0.0",
+    "description": "Lamware Middleware to utilize the official Metrics powertools",
+    "files": [
+        "build"
+    ],
+    "sideEffects": false,
+    "main": "./build/index.cjs.js",
+    "module": "./build/index.es.js",
+    "types": "./build/src/index.d.ts",
+    "license": "GPL-3.0-only",
+    "author": {
+        "name": "Evil Kiwi Limited",
+        "url": "https://evil.kiwi",
+        "email": "[email protected]"
+    },
+    "homepage": "https://github.com/tnotifier/lamware",
+    "bugs": {
+        "url": "https://github.com/tnotifier/lamware/issues"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/tnotifier/lamware.git"
+    },
+    "keywords": [
+        "lambda",
+        "middleware",
+        "typescript"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "clean": "rimraf build",
+        "prepack": "yarn build",
+        "build": "yarn clean && yarn compile",
+        "compile": "vite build",
+        "dev": "vite build --watch",
+        "lint": "eslint --ext .ts,vue --ignore-path .gitignore src"
+    },
+    "dependencies": {
+        "@aws-lambda-powertools/metrics": "^0.7.1",
+        "@tnotifier/lamware": "^1.1.5"
+    },
+    "devDependencies": {
+        "@types/node": "^14.18.12",
+        "eslint": "^8.11.0",
+        "rimraf": "^3.0.2",
+        "tslib": "^2.3.1",
+        "typescript": "^4.6.2",
+        "vite": "^2.8.6",
+        "vite-plugin-dts": "^0.9.10"
+    }
+}