Skip to content

Commit

Permalink
Merge pull request #149 from rackspace/issue/136-esm
Browse files Browse the repository at this point in the history
Add ESM Exports - Issue #136
  • Loading branch information
kernwig authored Feb 8, 2025
2 parents 3e94b2c + 7fd0f7b commit 0858efd
Show file tree
Hide file tree
Showing 98 changed files with 12,901 additions and 40,118 deletions.
20 changes: 4 additions & 16 deletions .editorconfig
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,9 @@
root = true

[*]
charset = utf-8
indent_style = space
indent_size = 4
insert_final_newline = true
trim_trailing_whitespace = true
end_of_line = lf

[*.md]
max_line_length = off
trim_trailing_whitespace = false

[*.json]
indent_style = space
indent_size = 2

[*.yml]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
21 changes: 21 additions & 0 deletions .github/workflows/pull-request.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
name: pull-request

on:
pull_request:
branches:
- main

jobs:
analyze:
runs-on: ubuntu-latest
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version-file: "package.json"
- name: Install dependencies
run: npm ci
- name: Run Analysis
run: npm run analyze
3 changes: 0 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@
.idea
.project
.classpath
.c9/
*.launch
.settings/
*.sublime-workspace
Expand All @@ -18,5 +17,3 @@ node_modules
npm-debug.log
coverage
dist
/experiment

6 changes: 6 additions & 0 deletions .prettierignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
.DS_Store
.serverless
.vscode
coverage
dist
node_modules
60 changes: 35 additions & 25 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,53 +9,63 @@ 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.
This collection is part of Rackspace Technology's commitment to give back to the open source community.
Find this and other Rackspace open source repositories on [GitHub](https://github.com/rackspace).


## Content

Each utility is described on its own page:

* [AwsHttps - HTTPS client with AWS Signature v4](docs/aws_https.md)
* [ElasticsearchClient - Communicate with AWS Elasticsearch](docs/elasticsearch_client.md)
* [ExpiringValue - Value that is instantiated on-demand and cached for a limited time](docs/expiring_value.md)
* [Injector - Light-weight and type-safe Dependency Injection](docs/injector.md)
* [LambdaUtils - AWS Lambda handler middleware](docs/lambda_utils.md)
* [Logger - CloudWatch and serverless-offline friendly logger](docs/logger.md)
* [StateStorage - Serverless state and configuration storage](docs/state_storage.md)
* [More Examples](docs/examples.md)
* [License](docs/license.md)
- [AwsHttps - HTTPS client with AWS Signature v4](docs/aws_https.md)
- [ElasticsearchClient - Communicate with AWS Elasticsearch](docs/elasticsearch_client.md)
- [ExpiringValue - Value that is instantiated on-demand and cached for a limited time](docs/expiring_value.md)
- [Injector - Light-weight and type-safe Dependency Injection](docs/injector.md)
- [LambdaUtils - AWS Lambda handler middleware](docs/lambda_utils.md)
- [Logger - CloudWatch and serverless-offline friendly logger](docs/logger.md)
- [StateStorage - Serverless state and configuration storage](docs/state_storage.md)
- [More Examples](docs/examples.md)
- [License](docs/license.md)

## Why "Sailplane"?

Onica's early OSS releases have had aviation themed names;
this may or may not have something to do with the CTO being a pilot. Nobody really knows.

Sailplane was selected for this *serverless* toolset by considering that
Sailplane was selected for this _serverless_ toolset by considering that
serverless is to computing without the complexities of a server,
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/<num>-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 <major | minor | patch>` 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.
5 changes: 4 additions & 1 deletion aws-https/README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,14 @@
# @sailplane/aws-http - HTTPS client with AWS Signature v4

## What?
The AwsHttps class is an HTTPS (notice, *not* HTTP) client purpose made for use in and with AWS environments.

The AwsHttps class is an HTTPS (notice, _not_ HTTP) client purpose made for use in and with AWS environments.

This is part of the [sailplane](https://github.com/rackspace/sailplane) library of
utilities for AWS Serverless in Node.js.

## Why?

- Simple Promise or async syntax
- Optionally authenticates to AWS via AWS Signature v4 using [aws4](https://www.npmjs.com/package/aws4)
- Familiar [options](https://nodejs.org/api/http.html#http_http_request_options_callback>)
Expand All @@ -15,4 +17,5 @@ utilities for AWS Serverless in Node.js.
- Easily extended for unit testing

## How?

See the [docs](https://github.com/rackspace/sailplane/blob/master/README.md) for usage and examples.
198 changes: 14 additions & 184 deletions aws-https/jest.config.js
Original file line number Diff line number Diff line change
@@ -1,187 +1,17 @@
// For a detailed explanation regarding each configuration property, visit:
// https://jestjs.io/docs/en/configuration.html

/** @type {import('ts-jest').JestConfigWithTsJest} **/
module.exports = {
// All imported modules in your tests should be mocked automatically
// automock: false,

// Stop running tests after the first failure
// bail: false,

// Respect "browser" field in package.json when resolving modules
// browser: false,

// The directory where Jest should store its cached dependency information
// cacheDirectory: "/var/folders/nq/vlcwldr96mj3y548v14s41qw0000gn/T/jest_dx",

// Automatically clear mock calls and instances between every test
// clearMocks: false,

// Indicates whether the coverage information should be collected while executing the test
collectCoverage: true,

// An array of glob patterns indicating a set of files for which coverage information should be collected
// collectCoverageFrom: null,

// The directory where Jest should output its coverage files
coverageDirectory: "../coverage",

// An array of regexp pattern strings used to skip coverage collection
// coveragePathIgnorePatterns: [
// "/node_modules/"
// ],

// A list of reporter names that Jest uses when writing coverage reports
coverageReporters: [
"json",
"text",
// "lcov",
"clover"
],

// An object that configures minimum threshold enforcement for coverage results
coverageThreshold: {
"./lib": {
branches: 85,
functions: 100,
statements: 100
}
testEnvironment: "node",
transform: {
"^.+.ts$": ["ts-jest", {}],
},

// Coverage
collectCoverage: true,
coverageThreshold: {
"./lib": {
branches: 90,
functions: 100,
statements: 95,
},

// Make calling deprecated APIs throw helpful error messages
// errorOnDeprecated: false,

// Force coverage collection from ignored files usin a array of glob patterns
// forceCoverageMatch: [],

// A path to a module which exports an async function that is triggered once before all test suites
// globalSetup: null,

// A path to a module which exports an async function that is triggered once after all test suites
// globalTeardown: null,

// A set of global variables that need to be available in all test environments
// globals: {},

// An array of directory names to be searched recursively up from the requiring module's location
// moduleDirectories: [
// "node_modules"
// ],

// An array of file extensions your modules use
// moduleFileExtensions: [
// "js",
// "json",
// "jsx",
// "node"
// ],

// A map from regular expressions to module names that allow to stub out resources with a single module
// moduleNameMapper: {},

// An array of regexp pattern strings, matched against all module paths before considered 'visible' to the module loader
// modulePathIgnorePatterns: [],

// Activates notifications for test results
// notify: false,

// An enum that specifies notification mode. Requires { notify: true }
// notifyMode: "always",

// A preset that is used as a base for Jest's configuration
// preset: null,
preset: 'ts-jest',

// Run tests from one or more projects
// projects: null,

// Use this configuration option to add custom reporters to Jest
// reporters: undefined,

// Automatically reset mock state between every test
// resetMocks: false,

// Reset the module registry before running each individual test
// resetModules: false,

// A path to a custom resolver
// resolver: null,

// Automatically restore mock state between every test
// restoreMocks: false,

// The root directory that Jest should scan for tests and modules within
rootDir: "./lib",

// A list of paths to directories that Jest should use to search for files in
// roots: [
// "<rootDir>"
// ],

// Allows you to use a custom runner instead of Jest's default test runner
// runner: "jest-runner",

// The paths to modules that run some code to configure or set up the testing environment before each test
// setupFiles: [],

// The path to a module that runs some code to configure or set up the testing framework before each test
// setupTestFrameworkScriptFile: null,

// A list of paths to snapshot serializer modules Jest should use for snapshot testing
// snapshotSerializers: [],

// The test environment that will be used for testing
testEnvironment: "node",

// Options that will be passed to the testEnvironment
// testEnvironmentOptions: {},

// Adds a location field to test results
// testLocationInResults: false,

// The glob patterns Jest uses to detect test files
// testMatch: [
// "**/__tests__/**/*.js?(x)",
// "**/?(*.)+(spec|test).js?(x)"
// ],

// An array of regexp pattern strings that are matched against all test paths, matched tests are skipped
// testPathIgnorePatterns: [
// "/node_modules/"
// ],

// The regexp pattern Jest uses to detect test files
// testRegex: "",

// This option allows the use of a custom results processor
// testResultsProcessor: null,

// This option allows use of a custom test runner
// testRunner: "jasmine2",

// This option sets the URL for the jsdom environment. It is reflected in properties such as location.href
// testURL: "http://localhost",

// Setting this value to "fake" allows the use of fake timers for functions such as "setTimeout"
// timers: "real",

// A map from regular expressions to paths to transformers
// transform: null,

// An array of regexp pattern strings that are matched against all source file paths, matched files will skip transformation
// transformIgnorePatterns: [
// "/node_modules/"
// ],

// An array of regexp pattern strings that are matched against all modules before the module loader will automatically return a mock for them
// unmockedModulePathPatterns: undefined,

// Indicates whether each individual test should be reported during the run
// verbose: null,

// An array of regexp patterns that are matched against all source file paths before re-running tests in watch mode
// watchPathIgnorePatterns: [],

// Whether to use watchman for file crawling
// watchman: true,
},
};
Loading

0 comments on commit 0858efd

Please sign in to comment.