Skip to main content
The @healthzkit/s3 package provides HealthAdapter helpers for AWS SDK v2 aws-sdk and v3 @aws-sdk/client-s3. Successful checks call ListBuckets and return ok with metadata.latencyMs, metadata.bucketCount, plus any fields from an optional metadata hook; failures return fail with the caught error. Install the adapter package and one AWS SDK:
Both SDKs are optional peers—install only the one you use.

Package entrypoints

  • @healthzkit/s3 - s3V2Adapter, s3V3Adapter, and their option types.
  • @healthzkit/s3/v2 - s3V2Adapter only.
  • @healthzkit/s3/v3 - s3V3Adapter only.
Use subpath imports when you want to avoid pulling the unused SDK into your bundle analysis path.

Shared options

Both factories accept BaseS3Options: Pass either config or an existing client (not both). The shape depends on the adapter (see below).

s3V2Adapter (aws-sdk)

Peer: aws-sdk >= 2. Uses the v2 S3 client and listBuckets(). Suitable for legacy services still on AWS SDK for JavaScript v2.

Config

The adapter lazily imports aws-sdk, constructs new AWS.S3(config) once, and reuses it across checks.

Existing client

s3V3Adapter (@aws-sdk/client-s3)

Peer: @aws-sdk/client-s3 >= 3. Uses S3Client and ListBucketsCommand. Prefer this for new code on AWS SDK for JavaScript v3.

Config

The adapter lazily imports @aws-sdk/client-s3, constructs new S3Client(config) once, and reuses it across checks.

Existing client

Scheduling

For S3 buckets that should not be queried on every probe, pair these adapters with a schedule on the check so readiness reads cached results (see Scheduling).

Resource ownership

AWS SDK v3 adapters destroy clients they construct from config on disposal. This also destroys the configured request handler and any agents that handler owns, including custom handlers or agents passed through config.requestHandler. If you share a handler or agent, construct the AWS client yourself and pass client to keep its lifecycle caller-owned. Supplied clients are never destroyed by the adapter. Use await kit.close() after draining application traffic, or await adapter.dispose?.() for direct adapter use. See Scheduling.