aws-lite

aws-lite

So, what is aws-lite?

aws-lite is a simple, extremely fast, extensible Node.js client for interacting with AWS services.

(It’s got good error reporting, too.)

You can think of it as a community-driven alternative to AWS’s JavaScript SDK.

Why not use aws-sdk / @aws-sdk/*?

Amazon has historically done a great job of maintaining its SDKs. However, AWS has deprecated its widely-adopted v2 SDK; its v3 SDK relies on generated code, resulting in large dependencies, poor performance, awkward semantics, difficult to understand documentation, and errors without usable stack traces.

We rely on and believe in AWS, so we built aws-lite to provide a simpler, faster, more stable position from which to work with AWS services in Node.js.

Features

  • 2x faster than AWS SDK v3
  • Simple semantics & straightforward promise-based interface
  • Human-readable documentation
  • Highly customizable
  • Errors with stack traces and line numbers
  • Built-in testing API with support for mocking and response queues
  • Built-in pagination
  • AWS credential provider chain support (SSO, IMDSv2 for ECS / EC2, etc.)
  • Secured with AWS Signature v4
  • Interacts with any AWS service without needing any plugins
  • Automatically parses / serializes JSON, AWS-flavored JSON, and XML request / response payloads
  • Easily integrates with local testing suites and AWS service mocks
  • Use existing service plugins, or develop your own
  • Debug mode for inspecting raw requests and responses
  • Just one dependency!

How does it work?

@aws-lite/client provides a basic client interface for quickly interacting with any AWS service. However, most folks will probably want to extend the client with service plugins, which provide ergonomic representations of AWS service API methods.

Because aws-lite and its plugins are authored from the ground up for performance and simplicity, aws-lite is 2x faster than AWS SDK, helping ensure that customer hot paths always receive sub-second responses:

Benchmark statistics - Time to respond, not including coldstart (DynamoDB) Benchmark statistics - Time to respond, not including coldstart

Learn more about aws-lite performance here.

Install aws-lite

Install the client:

npm i @aws-lite/client

Use the lower-level client to quickly interact with any AWS service API, or extend it with service plugins:

npm i @aws-lite/dynamodb

Types are available as optional @aws-lite/*-types packages:

npm i -D @aws-lite/dynamodb-types

Learn more about aws-lite types here.

Example

// Instantiate a client with the DynamoDB plugin
import awsLite from '@aws-lite/client'
const aws = await awsLite({
  region: 'us-west-1',
  plugins: [ import('@aws-lite/dynamodb') ]
})

// Easily interact with the AWS services your application relies on
await aws.DynamoDB.PutItem({
  TableName: '$table-name',
  Item: {
    // AWS-lite automatically de/serializes DynamoDB JSON
    pk: '$item-key',
    data: {
      ok: true,
      hi: 'friends'
    }
  }
})

await aws.DynamoDB.GetItem({
  TableName: '$table-name',
  Key: { pk: '$item-key' }
})
// {
//   Item: {
//     pk: '$item-key',
//     data: data: {
//       ok: true,
//       hi: 'friends'
//     }
//   }
// }

// Use the lower-level client to fire a custom GET request by specifying a `service` and `endpoint`
await aws({
  service: 'lambda',
  endpoint: '/2015-03-31/functions/$function-name/configuration',
})
// {
//   FunctionName: '$function-name',
//   Runtime: 'nodejs20.x',
//   ...
// }

// POST JSON by adding a `payload` property
await aws({
  service: 'lambda',
  endpoint: '/2015-03-31/functions/$function-name/invocations',
  payload: { ok: true },
})

Join the movement

aws-lite is an Apache 2.0-licensed open source project under the umbrella of OpenJS Foundation Architect. aws-lite is not in any way affiliated with Amazon Web Services, Inc. (AWS). All names and trademarks are the property of their respective owners.