sam-goodwin / itty-aws Goto Github PK

A teeny tiny ~49KB AWS SDK for TypeScript

Shell 0.76% TypeScript 99.24%

aws aws-lambda aws-lambda-node aws-sdk aws-sdk-javascript itty-router

itty-aws's Introduction

itty-aws

This is a teeny-tiny AWS SDK implementation for TypeScript using Proxies that fits everything into ~49 KB, including all Services and APIs. The name is an homage to the awesome itty-router.

🛠 This is a highly experimental API, do not use for anything serious.

Supported APIs

Known to work:

✅ Any modern API using plain JSON protocol should work out of the box.
✅ DynamoDB
✅ EventBridge
✅ SQS
✅ S3 CreateBucket, GetObject, HeadObject, PutObject, DeleteObject, ListObjectsV2
⛔️ S3 the remaining S3 APis likely don't work due to inconsistencies in the XML API.
⛔️ SNS (see: #2)

Why?

We want a lightweight AWS SDK that has no impact on Lambda cold starts and a standard API design. The AWS SDK v3 traded off usability to save on bundle size with the introduction of client.send(Command) and still didn't achieve a lightweight experience. None of this should be necessary - we can have our cake and eat it too!

Problems with AWS SDK v3

This project aims to eliminate the following issues with the official AWS SDK:

Bundle size and cold start times degrades as a piece of code uses more AWS APIs
Some APIs are excessively heavy (looking at you, S3).
Relying on an AWS SDK provided in the Lambda environment doesn't always save time either, since just require/import-ing it takes time because of how large the code is.
Bring back the client.apiName(..) design without compromising performance (e.g. dynamo.getItem(..) instead of dynamo.send(GetItemCommand)).

Status

The entire AWS SDK (including all Services and APIs) fits in to a

Minified bundle size of: 22 KB.
Un-minified bundle size of: 32 KB.

💪 It is possible to reduce this even further.

Installation

npm install itty-aws

Usage

Import the top-level AWS object from itty-aws and instantiate a client for the Service you want. The SDK is constant size, so your performance is not impacted by the number or choice of AWS services. The APIs are methods on the client - just like AWS SDK v2, except minus the .promise().

import { AWS } from "itty-aws";

const ddb = new AWS.DynamoDB();

const response = await ddb.getItem({
  TableName,
  Key: {
    pk: {
      S: "key",
    },
  },
});

console.log(response.Item);

How?

Instead of generating heavy classes and functions for the SDK like AWS does, we instead generate type declarations off of the AWS SDK v2 and provide a generic implementation for all clients using a Proxy. You can find this file in ./src/index.ts.

Known Issues

Performance has not been tested - it's possible that our use of https or fetch is slower than whatever magic the AWS SDK is doing.
We're still importing some heavy code from the AWS SDK for signing requests - including tslib (for whatever reason). We should investigate hand-rolling replacements that don't have these dependencies or at least minimize them.

itty-aws's People

Contributors

Stargazers

Watchers

Forkers

naorpeled jpbourgeon yehudacohen bronifty skyrpex

itty-aws's Issues

Proxy for Error Classes

Can we generate some types for the various AWS SDK errors, e.g. ConditionCheckFailed and then provide a proxy that lazily instantiates a class when accessed?

const dynamo = new AWS.DynamoDB();

try {
  await dynamo.putItem({ .. })
} catch (err) {
  if (err instanceof AWS.DynamoDB.ConditionCheckFailed) {
    
  }
}

CJS support

Is esm only right now - convert to hybrid

Advantages over using bundled AWS-SDK v3 for Node.js 18 runtime

Hey, I was reading the readme and I have one question:

Bundle size and cold start times degrades as a piece of code uses more AWS APIs

Is this really true, since aws-sdk v3 is present in the Lambda runtime anyways starting from Node.js 18? (source: https://docs.aws.amazon.com/lambda/latest/dg/lambda-runtimes.html) It's the same as it was for aws-sdk v2 for older runtime version

This argument about bundle size would still make sense, if this lib would be available for Node.js 16 and older runtimes, but there is hard requirement for Node.js 18 due to fetch lib

Test every AWS service API to guarantee feature parity and find potential additional loopholes

Writing these tests is time consuming. Is there a way to automate this systematic testing ?
Wouldn't it be terribly slow too : Shall we use some kind of snapshot testing against successful responses dwyl/aws-sdk-mock
Additionnaly, publishing an array that states feature parity for each supported service would be a nice add-on to the readme.

SNS support

SSM

Compare library performance against AWS-SDK

Performance has not been tested - it's possible that our use of https or fetch is slower than whatever magic the AWS SDK is doing.

As a first step, I suggest using a single one-shot performance benchmark against any standard service. This would test give a fast answer about how itty-aws compares to AWS-SDK. Then we can decide if performance should be systematically tested throughout API and services.

mcollina/autocannon is a maintained benchmarking tool that could be use for this purpose.
bestiejs/benchmark.js is more widely used but has been unmaintained for years now.

Look into https + aws4

Thanks to @krivachy for the suggestion of https://www.npmjs.com/package/aws4. Also found https://github.com/mhart/aws4fetch which works with Fetch API. I wonder if we can/should support both?

Bundle impact:

aws4 (8kB min, 2.9kB min + gzip) - https://bundlephobia.com/package/[email protected]
aws4fetch (7.2kB min, 2.9kB min + gzip) - https://bundlephobia.com/package/[email protected]

I think this approach would work better for browser environments but maybe worse for Lambda since the @aws-sdk/* libraries are included in the Lambda bundle. Still worth testing though, especially since importing @AWS-SDK has proven to be slow.

Could you clarify this project's purpose please? Is this a smart POC that will remain at the experimental level, or will it evolve into a production-ready community tool?

Anyway, keep up the good work 👏