From 5fab62e675a71689f407497a801524f0f8e66528 Mon Sep 17 00:00:00 2001 From: Adam Fanello Date: Wed, 29 Jan 2025 14:40:25 -0800 Subject: [PATCH] Issue #136 Add ES Module exports - Update documentation - Fix analyze scripts --- README.md | 39 ++++++++++++-------- aws-https/package.json | 2 +- docs/injector.md | 2 +- docs/lambda_utils.md | 23 +++++++----- elasticsearch-client/package.json | 2 +- expiring-value/package.json | 2 +- injector/package.json | 2 +- lambda-utils/package.json | 2 +- logger/package.json | 2 +- make.sh | 59 ------------------------------- package.json | 2 +- state-storage/package.json | 2 +- 12 files changed, 48 insertions(+), 91 deletions(-) delete mode 100755 make.sh diff --git a/README.md b/README.md index 6ced24a..9d281d9 100644 --- a/README.md +++ b/README.md @@ -9,11 +9,12 @@ we found certain patterns being used repeatedly, and code being copied from one These commonalities have been extracted, matured, and gathered into a reusable collection. Sailplane is the result: a collection of useful packages for use in developing code that runs in AWS. -They are primarily used in Lambda functions, but most are useful in other services that use the Node.js 18+ -runtime as well. +They are primarily designed for use in Lambda functions, but most are useful in other environments +that use the Node.js 20+ runtime as well. `ExpiringValue` is even useful in web browsers. -The Typescript source is compiled to ES6 Javascript for portability, along with Typescript type -definition files. While the typing provides the expected benefit, these utilities may be used in plain +The Typescript source is compiled to ES2020 Javascript and distributed with both ESModule and CommonJS +modules for portability, along with Typescript type definition files and map files. +While the typing provides the expected benefit, these utilities may be used in plain Javascript as well. Every tool is the genesis of real world needs, and they continue to evolve. @@ -45,16 +46,26 @@ as a sailplane is to flight without the complexities of an airplane. And that's it. Also, the NPM scope was available. -![](docs/sailplane.png) - ## Development -Use the `make.sh` script to build all of the projects in an order that resolves the dependencies between them. +This is a monorepo with shared development tools at the root level. Each subdirectory is a +project. Use the `npm run` scripts in each package, or from the root workspace to run the +script on all packages. + +### Making Changes + +1. Create an [issue in Github](https://github.com/rackspace/sailplane/issues). Get approval from the community. +2. Create a branch off of `main`. The branch name should be like `issue/-brief-summary` +3. Make your change and test it thoroughly with unit tests and a project using it. +4. Run `npm run analyze` from the root workspace and resolve all errors. +5. Commit to your git branch and open a [pull request](https://github.com/rackspace/sailplane/pulls). + - Do not change the version in `package.json`. + +### Publish a Release + +This is managed from each library package, as they are individually released to NPM. -``` -$ ./make.sh clean # delete all node_modules directories -$ ./make.sh build # npm install, test, and build all packages -$ ./make.sh check # check what packages need to be published -$ ./make.sh publish # npm publish packages with new version numbers (must have bump versions first and have permission) -$ ./make.sh all # do clean, build, & publish -``` +1. Run `npm run clean && npm run analyze` to confirm that all code builds and tests pass. +2. Use `npm version ` to bump the version and tag it in git. ([docs](https://docs.npmjs.com/cli/v10/commands/npm-version)) +3. Use `npm publish` to publish the change to NPM. You must have credentials. ([docs](https://docs.npmjs.com/cli/v10/commands/npm-publish)) +4. Commit & Push updates to git. diff --git a/aws-https/package.json b/aws-https/package.json index 35e11da..de297c7 100644 --- a/aws-https/package.json +++ b/aws-https/package.json @@ -10,7 +10,7 @@ "typescript" ], "scripts": { - "analyze": "npm run build && npm run lint && npm test && npm run prettier", + "analyze": "npm run build && npm run lint && npm test", "clean": "rm -rf coverage dist", "build": "tsup", "dev": "tsup --watch", diff --git a/docs/injector.md b/docs/injector.md index fd90e3c..cc0ee10 100644 --- a/docs/injector.md +++ b/docs/injector.md @@ -20,7 +20,7 @@ As of v3, Injector also supports a Typescript decorator for registering classes. ## Install ```shell -npm install @sailplane/injector @sailplane/logger bottlejs@1.7 +npm install @sailplane/injector @sailplane/logger bottlejs@2 ``` ## Configuration diff --git a/docs/lambda_utils.md b/docs/lambda_utils.md index 5a312bd..45b6dee 100644 --- a/docs/lambda_utils.md +++ b/docs/lambda_utils.md @@ -44,39 +44,44 @@ or use it as an example to write your own, to add more middleware! ## Install -**To use LambdaUtils v6.x with Middy v4.x.x (latest):** +### LambdaUtils v7.x with Middy v6.x.x (latest) + +**Works best with ES Modules, not CommonJS.** See [Middy Upgrade Notes](https://middy.js.org/docs/upgrade/5-6). ```shell -npm install @sailplane/lambda-utils@6 @sailplane/logger @middy/core@4 @middy/http-cors@4 @middy/http-event-normalizer@4 @middy/http-header-normalizer@4 @middy/http-json-body-parser@4 +npm install @sailplane/lambda-utils@7 @sailplane/logger @middy/core@6 @middy/http-cors@6 @middy/http-event-normalizer@6 @middy/http-header-normalizer@6 @middy/http-json-body-parser@6 ``` The extra `@middy/` middleware packages are optional if you write your own wrapper function that does not use them. See below. -**To use LambdaUtils v4.x or v5.x with Middy v2.x.x:** +### LambdaUtils v6.x with Middy v4.x.x ```shell -npm install @sailplane/lambda-utils@4 @sailplane/logger @middy/core@2 @middy/http-cors@2 @middy/http-event-normalizer@2 @middy/http-header-normalizer@2 @middy/http-json-body-parser@2 +npm install @sailplane/lambda-utils@6 @sailplane/logger @middy/core@4 @middy/http-cors@4 @middy/http-event-normalizer@4 @middy/http-header-normalizer@4 @middy/http-json-body-parser@4 ``` -The extra @middy/ middleware packages are optional if you write your own wrapper function that does not use them. +The extra `@middy/` middleware packages are optional if you write your own wrapper function that does not use them. See below. -**To use LambdaUtils v3.x with Middy v1.x.x:** +### LambdaUtils v4.x or v5.x with Middy v2.x.x ```shell -npm install @sailplane/lambda-utils@3 @sailplane/logger @middy/core@1 @middy/http-cors@1 @middy/http-event-normalizer@1 @middy/http-header-normalizer@1 @middy/http-json-body-parser@1 +npm install @sailplane/lambda-utils@4 @sailplane/logger @middy/core@2 @middy/http-cors@2 @middy/http-event-normalizer@2 @middy/http-header-normalizer@2 @middy/http-json-body-parser@2 ``` The extra @middy/ middleware packages are optional if you write your own wrapper function that does not use them. See below. -**To use LambdaUtils v2.x with Middy v0.x.x:** +### LambdaUtils v3.x with Middy v1.x.x ```shell -npm install @sailplane/lambda-utils@2 @sailplane/logger middy@0 +npm install @sailplane/lambda-utils@3 @sailplane/logger @middy/core@1 @middy/http-cors@1 @middy/http-event-normalizer@1 @middy/http-header-normalizer@1 @middy/http-json-body-parser@1 ``` +The extra @middy/ middleware packages are optional if you write your own wrapper function that does not use them. +See below. + ## Upgrading To upgrade from older versions of lambda-utils, remove the old lambda-utils and middy dependencies diff --git a/elasticsearch-client/package.json b/elasticsearch-client/package.json index 72b20de..9383623 100644 --- a/elasticsearch-client/package.json +++ b/elasticsearch-client/package.json @@ -8,7 +8,7 @@ "typescript" ], "scripts": { - "analyze": "npm run build && npm run lint && npm test && npm run prettier", + "analyze": "npm run build && npm run lint && npm test", "clean": "rm -rf coverage dist", "build": "tsup", "dev": "tsup --watch", diff --git a/expiring-value/package.json b/expiring-value/package.json index 9e57486..278357e 100644 --- a/expiring-value/package.json +++ b/expiring-value/package.json @@ -9,7 +9,7 @@ "typescript" ], "scripts": { - "analyze": "npm run build && npm run lint && npm test && npm run prettier", + "analyze": "npm run build && npm run lint && npm test", "clean": "rm -rf coverage dist", "build": "tsup", "dev": "tsup --watch", diff --git a/injector/package.json b/injector/package.json index 40edfdc..a82012c 100644 --- a/injector/package.json +++ b/injector/package.json @@ -8,7 +8,7 @@ "typescript" ], "scripts": { - "analyze": "npm run build && npm run lint && npm test && npm run prettier", + "analyze": "npm run build && npm run lint && npm test", "clean": "rm -rf coverage dist", "build": "tsup", "dev": "tsup --watch", diff --git a/lambda-utils/package.json b/lambda-utils/package.json index a57dec4..d831b3b 100644 --- a/lambda-utils/package.json +++ b/lambda-utils/package.json @@ -11,7 +11,7 @@ "middy" ], "scripts": { - "analyze": "npm run build && npm run lint && npm test && npm run prettier", + "analyze": "npm run build && npm run lint && npm test", "clean": "rm -rf coverage dist", "build": "tsup", "dev": "tsup --watch", diff --git a/logger/package.json b/logger/package.json index ebdb1dd..02946f7 100644 --- a/logger/package.json +++ b/logger/package.json @@ -10,7 +10,7 @@ "typescript" ], "scripts": { - "analyze": "npm run build && npm run lint && npm test && npm run prettier", + "analyze": "npm run build && npm run lint && npm test", "clean": "rm -rf coverage dist", "build": "tsup", "dev": "tsup --watch", diff --git a/make.sh b/make.sh deleted file mode 100755 index 256a1e2..0000000 --- a/make.sh +++ /dev/null @@ -1,59 +0,0 @@ -#!/bin/bash -# Requires one command: -# - "clean" - delete all node_modules -# - "build" - npm install, test, and build all packages -# - "check" - check what packages need to be published -# - "publish" - npm publish packages with new version numbers -# - "all" - do clean, build, & publish -COMMAND=$1 - -PROJECTS="expiring-value logger lambda-utils aws-https elasticsearch-client injector state-storage" - -if [[ $COMMAND == clean || $COMMAND == all ]]; then - for DIR in $PROJECTS - do - echo - echo "***** Clean Package: $DIR" - echo - pushd $DIR || exit $? - rm -rf node_modules - popd || exit $? - done -fi - -if [[ $COMMAND == build || $COMMAND == all ]]; then - # First build all - quit to avoid publishing if anything fails - for DIR in $PROJECTS - do - echo - echo "***** Build Package: $DIR" - echo - pushd $DIR || exit $? - ( npm install && npm run test && npm run build) || exit $? - popd || exit $? - done -fi - -if [[ $COMMAND == check || $COMMAND == publish || $COMMAND == all ]]; then - for DIR in $PROJECTS - do - pushd $DIR || exit $? - NAME=$(cat package.json |jq .name|tr -d '"') - VER=$(cat package.json |jq .version|tr -d '"') - if [[ -z "$(npm info ${NAME}@${VER} version 2>/dev/null)" ]]; then - echo - echo "***** Publish: ${NAME}@${VER}" - echo - if [[ $COMMAND != check ]]; then - npm publish || exit $? - fi - else - echo - echo "***** Already Exists: ${NAME}@${VER}" - echo - fi - popd || exit $? - done -fi - -exit 0 diff --git a/package.json b/package.json index 55e372a..0c993be 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,7 @@ "npm": ">=10.3.0 <11" }, "scripts": { - "analyze": "npm run analyze -ws", + "analyze": "npm run analyze -ws && npm run prettier", "build": "npm run build -ws", "clean": "npm run clean -ws && rm -rf tsconfig.tsbuildinfo", "clean:all": "npm run clean && find . -name node_modules -maxdepth 2 -type d -exec rm -rf {} +", diff --git a/state-storage/package.json b/state-storage/package.json index 627693e..a738b0c 100644 --- a/state-storage/package.json +++ b/state-storage/package.json @@ -11,7 +11,7 @@ "typescript" ], "scripts": { - "analyze": "npm run build && npm run lint && npm test && npm run prettier", + "analyze": "npm run build && npm run lint && npm test", "clean": "rm -rf coverage dist", "build": "tsup", "dev": "tsup --watch",